@seekora-ai/ui-sdk-react 0.2.11 → 0.2.13

package/dist/src/index.d.ts

@@ -2,8 +2,8 @@ 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$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 { 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, PriceRange, ProductBadge, ProductOption, ProductVariant } from '@seekora-ai/ui-sdk-types';
+export { FieldMapping, PriceRange, ProductBadge, ProductOption, ProductVariant, 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';
 
@@ -41,6 +41,8 @@ interface SearchBarProps {
     className?: string;
     style?: React__default.CSSProperties;
     theme?: SearchBarTheme;
+    /** Show loading state when fetching and no previous suggestions (default false: show previous results until new render) */
+    showLoadingState?: boolean;
     renderSuggestion?: (suggestion: string, index: number) => React__default.ReactNode;
     renderLoading?: () => React__default.ReactNode;
 }
@@ -75,6 +77,8 @@ interface SearchResultsProps {
     onResultClick?: (result: ResultItem, index: number) => void;
     renderResult?: (result: ResultItem, index: number, isActive?: boolean) => React__default.ReactNode;
     renderEmpty?: () => React__default.ReactNode;
+    /** Show loading state when fetching and no previous results (default false: show previous results until new render) */
+    showLoadingState?: boolean;
     renderLoading?: () => React__default.ReactNode;
     renderError?: (error: Error) => React__default.ReactNode;
     className?: string;
@@ -533,6 +537,8 @@ interface InfiniteHitsProps {
     renderHit?: (hit: ResultItem, index: number) => React__default.ReactNode;
     /** Custom render for empty state */
     renderEmpty?: () => React__default.ReactNode;
+    /** Show initial loading when fetching and no hits yet (default false: no loading screen) */
+    showInitialLoading?: boolean;
     /** Custom render for loading state */
     renderLoading?: () => React__default.ReactNode;
     /** Custom render for "Show More" button */
@@ -888,6 +894,8 @@ interface RelatedProductsProps extends BaseRecommendationProps {
     items?: RecommendationItem[];
     /** Loading state */
     loading?: boolean;
+    /** Show loading state when fetching and no previous items (default false: show previous results until new render) */
+    showLoadingState?: boolean;
 }
 declare const RelatedProducts: React__default.FC<RelatedProductsProps>;
 interface TrendingItemsProps extends BaseRecommendationProps {
@@ -895,6 +903,8 @@ interface TrendingItemsProps extends BaseRecommendationProps {
     items?: RecommendationItem[];
     /** Loading state */
     loading?: boolean;
+    /** Show loading state when fetching and no previous items (default false: show previous results until new render) */
+    showLoadingState?: boolean;
     /** Facet name for trending (if using facet data) */
     facetName?: string;
 }
@@ -906,6 +916,8 @@ interface FrequentlyBoughtTogetherProps extends BaseRecommendationProps {
     items?: RecommendationItem[];
     /** Loading state */
     loading?: boolean;
+    /** Show loading state when fetching and no previous items (default false: show previous results until new render) */
+    showLoadingState?: boolean;
     /** Show "Add all to cart" button */
     showAddAllButton?: boolean;
     /** Callback when "Add all" is clicked */
@@ -952,6 +964,8 @@ interface QuerySuggestionsProps {
     minQueryLength?: number;
     onSuggestionClick?: (suggestion: string) => void;
     renderSuggestion?: (suggestion: SuggestionItem$2, index: number) => React__default.ReactNode;
+    /** Show loading state when fetching and no previous suggestions (default false: show previous results until new render) */
+    showLoadingState?: boolean;
     renderLoading?: () => React__default.ReactNode;
     renderEmpty?: () => React__default.ReactNode;
     showTitle?: boolean;
@@ -991,7 +1005,7 @@ interface QuerySuggestionsDropdownProps extends QuerySuggestionsEventHandlers {
     maxRecentSearches?: number;
     /** Show suggestion counts */
     showCounts?: boolean;
-    /** Show loading state */
+    /** Show loading state (default false: show previous results until new results render) */
     showLoading?: boolean;
     /** Show empty state when no results */
     showEmptyState?: boolean;
@@ -1104,6 +1118,10 @@ interface RichQuerySuggestionsProps extends QuerySuggestionsEventHandlers {
     header?: React__default.ReactNode;
     /** Custom footer content */
     footer?: React__default.ReactNode;
+    /** Show loading overlay when fetching (default false: show previous results until new results render) */
+    showLoadingOverlay?: boolean;
+    /** Custom render for loading overlay (only when showLoadingOverlay is true) */
+    renderLoading?: () => React__default.ReactNode;
     /** Dropdown width */
     width?: string | number;
     /** Dropdown max height */
@@ -1586,6 +1604,13 @@ interface SuggestionListProps {
     className?: string;
     style?: React__default.CSSProperties;
     listClassName?: string;
+    /**
+     * When true, show a loading state when fetching and no previous suggestions exist.
+     * When false (default), show previous results until new results render; no loading screen.
+     */
+    showLoadingState?: boolean;
+    /** Custom render for loading state (only when showLoadingState is true and loading with no items). */
+    renderLoading?: () => React__default.ReactNode;
     /**
      * When true (default), suggestion text with <mark>...</mark> is rendered
      * with those segments highlighted. When false, plain text is shown.
@@ -1596,7 +1621,7 @@ interface SuggestionListProps {
     highlightMarkupOptions?: HighlightMarkupOptions;
     renderItem?: (suggestion: _seekora_ai_ui_sdk_types.SuggestionItem, index: number, isActive: boolean, onSelect: () => void) => React__default.ReactNode;
 }
-declare function SuggestionList({ maxItems, className, style, listClassName, enableHighlightMarkup, highlightMarkupOptions, renderItem, }: SuggestionListProps): React__default.JSX.Element | null;
+declare function SuggestionList({ maxItems, className, style, listClassName, showLoadingState, renderLoading, enableHighlightMarkup, highlightMarkupOptions, renderItem, }: SuggestionListProps): React__default.JSX.Element | null;
 
 /**
  * SuggestionItem – single text suggestion row (primitive)
@@ -1627,6 +1652,33 @@ interface SuggestionItemProps {
 }
 declare function SuggestionItem$1({ suggestion, index, isActive, onSelect, className, style, enableHighlightMarkup, highlightMarkupOptions, renderHighlight, }: SuggestionItemProps): React__default.JSX.Element;
 
+/**
+ * ActionButtons – card action buttons (add to cart, wishlist, buy now, quick view)
+ *
+ * Renders a set of action buttons for product cards. Can be positioned absolutely
+ * over the image (on hover) or inline below the card content.
+ */
+
+type ActionButtonType = 'addToCart' | 'wishlist' | 'buyNow' | 'quickView' | 'compare';
+interface ActionButton {
+    type: ActionButtonType;
+    label?: string;
+    icon?: React__default.ReactNode;
+    onClick?: (e: React__default.MouseEvent) => void;
+    disabled?: boolean;
+    loading?: boolean;
+}
+interface ActionButtonsProps {
+    buttons: ActionButton[];
+    layout?: 'horizontal' | 'vertical' | 'overlay';
+    position?: 'top-right' | 'bottom-center' | 'inline';
+    showLabels?: boolean;
+    size?: 'small' | 'medium' | 'large';
+    className?: string;
+    style?: React__default.CSSProperties;
+}
+declare function ActionButtons({ buttons, layout, position, showLabels, size, className, style, }: ActionButtonsProps): React__default.JSX.Element;
+
 /**
  * ItemCard – generic item tile (primitive)
  *
@@ -1663,8 +1715,16 @@ interface ItemCardProps {
     asLink?: boolean;
     /** When multiple images, use ImageDisplay with this variant */
     imageVariant?: ImageDisplayVariant$1;
+    /** Layout direction: vertical (default) or horizontal (image left, content right) */
+    layout?: 'vertical' | 'horizontal';
+    /** Action buttons (add to cart, wishlist, etc.) */
+    actionButtons?: ActionButton[];
+    /** Action buttons position */
+    actionButtonsPosition?: 'overlay-top-right' | 'overlay-bottom' | 'inline';
+    /** Show action button labels */
+    showActionLabels?: boolean;
 }
-declare function ItemCard({ item, position, onSelect, className, style, asLink, imageVariant, }: ItemCardProps): React__default.JSX.Element;
+declare function ItemCard({ item, position, onSelect, className, style, asLink, imageVariant, layout, actionButtons, actionButtonsPosition, showActionLabels, }: ItemCardProps): React__default.JSX.Element;
 
 /**
  * ItemGrid – generic grid of items (primitive)
@@ -1693,770 +1753,1055 @@ interface ItemGridProps<T = GenericItem> {
 }
 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;
+/** Maps client's data fields to component expected fields */
+interface SuggestionFieldMapping {
+    /** Field path for suggestion text (e.g., "query", "searchTerm", "text") */
+    query: string;
+    /** Field path for suggestion count/popularity */
+    count?: string;
+    /** Field path for object ID */
+    id?: string;
+    /** Field path for categories array */
+    categories?: string;
+    /** Field path for highlighted text */
+    highlighted?: string;
+    /** Custom field mappings */
+    custom?: Record<string, string>;
 }
-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;
+/** Maps client's product fields to component expected fields */
+interface ProductFieldMapping {
+    /** Field path for product ID */
+    id: string;
+    /** Field path for product title/name */
+    title: string;
+    /** Field path for product image URL */
+    image?: string;
+    /** Field path for product price */
+    price?: string;
+    /** Field path for original/compare price */
+    comparePrice?: string;
+    /** Field path for product URL */
+    url?: string;
+    /** Field path for brand name */
+    brand?: string;
+    /** Field path for category */
+    category?: string;
+    /** Field path for rating */
+    rating?: string;
+    /** Field path for review count */
+    reviewCount?: string;
+    /** Field path for discount percentage */
+    discount?: string;
+    /** Field path for availability/in stock */
+    inStock?: string;
+    /** Field path for currency */
+    currency?: string;
+    /** Field path for multiple images */
+    images?: string;
+    /** Field path for original/compare price (alias) */
+    originalPrice?: string;
+    /** Field path for availability */
+    available?: string;
+    /** Field path for product options (Color, Size axes) */
+    options?: string;
+    /** Field path for product variants */
+    variants?: string;
+    /** Field path for product tags */
+    tags?: string;
+    /** Custom field mappings */
+    custom?: Record<string, 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;
+/** Maps client's category/tab fields */
+interface CategoryFieldMapping {
+    id: string;
+    label: string;
+    count?: string;
+    icon?: string;
+    image?: 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;
+/** Maps client's brand fields */
+interface BrandFieldMapping {
+    id?: string;
+    name: string;
+    logo?: string;
+    count?: string;
 }
-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;
+type DropdownLayout = 'list' | 'two-column' | 'three-column' | 'grid' | 'hero' | 'full-width' | 'mobile-sheet' | 'overlay';
+type ProductCardSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+type ProductCardStyle = 'minimal' | 'standard' | 'detailed' | 'compact' | 'horizontal';
+/** Available dropdown variants */
+type SuggestionDropdownVariant$1 = 'amazon' | 'google' | 'pinterest' | 'spotlight' | 'shopify' | 'mobile-sheet' | 'minimal';
+interface VisualConfig {
+    /** Overall dropdown layout */
+    layout?: DropdownLayout;
+    /** Show/hide shadows */
+    shadows?: boolean;
+    /** Border radius (px or CSS value) */
+    borderRadius?: number | string;
+    /** Animation style */
+    animation?: 'none' | 'fade' | 'slide' | 'scale' | 'spring';
+    /** Animation duration in ms */
+    animationDuration?: number;
+    /** Blur background when open */
+    backdropBlur?: boolean;
+    /** Show dividers between sections */
+    showDividers?: boolean;
+    /** Compact mode (reduced padding) */
+    compact?: boolean;
 }
-declare function TrendingList({ title, maxItems, className, style, listClassName, renderItem, }: TrendingListProps): React__default.JSX.Element | null;
-
-/**
- * SuggestionsLoading – loading indicator (primitive)
- */
-
-interface SuggestionsLoadingProps {
+type SectionType = 'suggestions' | 'recent' | 'trending' | 'products' | 'categories' | 'brands' | 'collections' | 'pages' | 'custom';
+interface SectionConfig {
+    /** Section identifier */
+    id: SectionType | string;
+    /** Section title (can be ReactNode for custom rendering) */
+    title?: string | ReactNode;
+    /** Whether section is enabled */
+    enabled?: boolean;
+    /** Maximum items to show */
+    maxItems?: number;
+    /** Section display order (lower = higher) */
+    order?: number;
+    /** Section-specific layout override */
+    layout?: 'list' | 'grid' | 'horizontal-scroll' | 'chips';
+    /** Number of columns for grid layout */
+    columns?: number;
+    /** Show "View All" link */
+    showViewAll?: boolean;
+    /** View All link URL or handler */
+    viewAllLink?: string;
+    /** Custom CSS class */
     className?: string;
-    style?: React__default.CSSProperties;
-    text?: string;
+    /** Custom styles */
+    style?: CSSProperties;
+    /** Custom renderer for entire section */
+    render?: (data: any[], config: SectionConfig) => ReactNode;
+    /** Custom renderer for individual items */
+    renderItem?: (item: any, index: number) => ReactNode;
+    /** Empty state message */
+    emptyMessage?: string;
+    /** Icon for section header */
+    icon?: ReactNode;
 }
-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;
+interface ProductDisplayConfig {
+    /** Card size */
+    size?: ProductCardSize;
+    /** Card style */
+    style?: ProductCardStyle;
+    /** Show product image */
+    showImage?: boolean;
+    /** Image aspect ratio */
+    imageAspectRatio?: '1:1' | '4:3' | '3:4' | '16:9' | 'auto';
+    /** Show price */
+    showPrice?: boolean;
+    /** Show compare/original price */
+    showComparePrice?: boolean;
+    /** Show discount badge */
+    showDiscount?: boolean;
+    /** Show brand */
+    showBrand?: boolean;
+    /** Show rating */
+    showRating?: boolean;
+    /** Show stock status */
+    showStock?: boolean;
+    /** Show add to cart button */
+    showAddToCart?: boolean;
+    /** Currency symbol */
+    currency?: string;
+    /** Currency position */
+    currencyPosition?: 'before' | 'after';
+    /** Decimal places for price */
+    priceDecimals?: number;
+    /** Truncate title after N lines */
+    titleLines?: number;
+    /** Hover effect */
+    hoverEffect?: 'none' | 'lift' | 'glow' | 'scale' | 'border';
+    /** Image placeholder */
+    imagePlaceholder?: ReactNode;
+    /** Lazy load images */
+    lazyLoadImages?: boolean;
+    /** Show variant swatches on card */
+    showVariants?: boolean;
+    /** Which option names to show as swatches (e.g., ['Color']). Default: all */
+    variantOptionsToShow?: string[];
+    /** Max variant values before "+N more" (default: 5) */
+    maxVariantValues?: number;
+    /** Show price range when variants have different prices */
+    showPriceRange?: boolean;
+    /** Show badges (sale, new, sold out, etc.) */
+    showBadges?: boolean;
+    /** Custom badge extractor from tags */
+    badgeExtractor?: (tags?: string[], product?: any) => _seekora_ai_ui_sdk_types.ProductBadge[];
 }
-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;
+interface SuggestionDisplayConfig {
+    /** Show search icon */
+    showIcon?: boolean;
+    /** Custom icon */
+    icon?: ReactNode;
+    /** Show hit count */
+    showCount?: boolean;
+    /** Show categories inline */
+    showCategories?: boolean;
+    /** Max categories to show */
+    maxCategories?: number;
+    /** Highlight matching text */
+    highlightMatches?: boolean;
+    /** Highlight style */
+    highlightStyle?: CSSProperties;
+    /** Show arrow on hover */
+    showArrow?: boolean;
+    /** Category click behavior */
+    categoryClickable?: boolean;
+}
+interface DropdownThemeConfig {
+    /** Light/dark mode */
+    mode?: 'light' | 'dark' | 'auto';
+    /** Primary brand color */
+    primaryColor?: string;
+    /** Background color */
+    backgroundColor?: string;
+    /** Surface color (cards, sections) */
+    surfaceColor?: string;
+    /** Text color */
+    textColor?: string;
+    /** Secondary text color */
+    textSecondaryColor?: string;
+    /** Border color */
+    borderColor?: string;
+    /** Hover background */
+    hoverColor?: string;
+    /** Highlight/match color */
+    highlightColor?: string;
+    /** Success color (in stock, etc.) */
+    successColor?: string;
+    /** Error color (out of stock, etc.) */
+    errorColor?: string;
+    /** Font family */
+    fontFamily?: string;
+    /** Base font size */
+    fontSize?: number | string;
+    /** Border radius */
+    borderRadius?: number | string;
+    /** Box shadow */
+    boxShadow?: string;
+    /** Custom CSS variables */
+    cssVariables?: Record<string, string>;
+}
+interface AnalyticsConfig {
+    /** Enable analytics */
+    enabled?: boolean;
+    /** Track suggestion clicks */
+    trackSuggestionClicks?: boolean;
+    /** Track product clicks */
+    trackProductClicks?: boolean;
+    /** Track impressions */
+    trackImpressions?: boolean;
+    /** Impression debounce time (ms) */
+    impressionDebounce?: number;
+    /** Track category clicks */
+    trackCategoryClicks?: boolean;
+    /** Track brand clicks */
+    trackBrandClicks?: boolean;
+    /** Track search submissions */
+    trackSearchSubmit?: boolean;
+    /** Custom analytics tags */
+    tags?: string[];
+    /** User ID for personalization */
+    userId?: string;
+    /** Session ID */
+    sessionId?: string;
+    /** Custom event handler */
+    onEvent?: (eventType: string, data: any) => void;
+}
+interface DropdownEventHandlers<TSuggestion = any, TProduct = any, TCategory = any, TBrand = any> {
+    /** Suggestion selected */
+    onSuggestionSelect?: (suggestion: TSuggestion, index: number) => void;
+    /** Product clicked */
+    onProductClick?: (product: TProduct, index: number) => void;
+    /** Category clicked */
+    onCategoryClick?: (category: TCategory, suggestion?: TSuggestion) => void;
+    /** Brand clicked */
+    onBrandClick?: (brand: TBrand) => void;
+    /** Tab/filter changed */
+    onTabChange?: (tabId: string, tab?: any) => void;
+    /** Recent search clicked */
+    onRecentClick?: (query: string) => void;
+    /** Recent search removed */
+    onRecentRemove?: (query: string) => void;
+    /** Clear all recent searches */
+    onRecentClearAll?: () => void;
+    /** View all clicked */
+    onViewAll?: (section: SectionType | string) => void;
+    /** Search submitted */
+    onSearchSubmit?: (query: string) => void;
+    /** Dropdown opened */
+    onOpen?: () => void;
+    /** Dropdown closed */
+    onClose?: () => void;
+    /** Keyboard navigation */
+    onNavigate?: (direction: 'up' | 'down' | 'left' | 'right', index: number) => void;
+    /** Add to cart clicked (if enabled) */
+    onAddToCart?: (product: TProduct) => void;
+}
+interface AccessibilityConfig {
+    /** ARIA label for dropdown */
+    ariaLabel?: string;
+    /** ARIA labelledby */
+    ariaLabelledBy?: string;
+    /** Announce selection to screen readers */
+    announceSelection?: boolean;
+    /** Custom announcement text */
+    getAnnouncementText?: (item: any, type: string) => string;
+    /** Keyboard navigation enabled */
+    keyboardNavigation?: boolean;
+    /** Focus trap (keep focus within dropdown) */
+    focusTrap?: boolean;
+    /** Auto focus first item */
+    autoFocus?: boolean;
+    /** Close on escape */
+    closeOnEscape?: boolean;
+    /** Close on click outside */
+    closeOnClickOutside?: boolean;
+}
+interface BaseDropdownProps<TSuggestion = any, TProduct = any, TCategory = any, TBrand = any> extends DropdownEventHandlers<TSuggestion, TProduct, TCategory, TBrand> {
+    /** Current search query */
+    query: string;
+    /** Whether dropdown is open/visible */
+    isOpen?: boolean;
+    /** Loading state */
+    loading?: boolean;
+    /** Error state */
+    error?: Error | string | null;
+    /** Suggestion items */
+    suggestions?: TSuggestion[];
+    /** Product items */
+    products?: TProduct[];
+    /** Category/filter tabs */
+    categories?: TCategory[];
+    /** Brand items */
+    brands?: TBrand[];
+    /** Recent searches (strings or objects) */
+    recentSearches?: string[] | Array<{
+        query: string;
+        timestamp?: number;
+    }>;
+    /** Trending searches */
+    trendingSearches?: string[] | TSuggestion[];
+    /** Filtered tabs with products */
+    filteredTabs?: Array<{
+        id: string;
+        label: string;
+        products?: TProduct[];
+        nb_hits?: number;
+        filter?: string;
+    }>;
+    /** Currently active tab ID */
+    activeTab?: string;
+    /** Map suggestion data fields */
+    suggestionFields?: SuggestionFieldMapping;
+    /** Map product data fields */
+    productFields?: ProductFieldMapping;
+    /** Map category data fields */
+    categoryFields?: CategoryFieldMapping;
+    /** Map brand data fields */
+    brandFields?: BrandFieldMapping;
+    /** Section configurations */
+    sections?: SectionConfig[];
+    /** Product display config */
+    productDisplay?: ProductDisplayConfig;
+    /** Suggestion display config */
+    suggestionDisplay?: SuggestionDisplayConfig;
+    /** Visual/layout config */
+    visual?: VisualConfig;
+    /** Theme config */
+    theme?: DropdownThemeConfig;
+    /** Analytics config */
+    analytics?: AnalyticsConfig;
+    /** Accessibility config */
+    accessibility?: AccessibilityConfig;
+    /** Dropdown width */
+    width?: string | number;
+    /** Dropdown max height */
+    maxHeight?: string | number;
+    /** Dropdown min height */
+    minHeight?: string | number;
+    /** Z-index */
+    zIndex?: number;
+    /** Root CSS class */
+    className?: string;
+    /** Root inline styles */
+    style?: CSSProperties;
+    /** CSS classes for parts */
+    classNames?: Partial<DropdownClassNames>;
+    /** Inline styles for parts */
+    styles?: Partial<DropdownStyles>;
+    /** Custom header */
+    header?: ReactNode;
+    /** Custom footer */
+    footer?: ReactNode;
+    /** Custom loading state */
+    /** Show loading state when fetching and no previous items (default false: show previous results until new render) */
+    showLoadingState?: boolean;
+    renderLoading?: () => ReactNode;
+    /** Custom empty state */
+    renderEmpty?: (query: string) => ReactNode;
+    /** Custom error state */
+    renderError?: (error: Error | string) => ReactNode;
+    /** Reference to input element (for focus management) */
+    inputRef?: React.RefObject<HTMLInputElement>;
+}
+interface DropdownClassNames {
+    root: string;
+    container: string;
+    header: string;
+    content: string;
+    footer: string;
+    section: string;
+    sectionHeader: string;
+    sectionTitle: string;
+    sectionContent: string;
+    sectionViewAll: string;
+    suggestionsList: string;
+    suggestionItem: string;
+    suggestionItemActive: string;
+    suggestionIcon: string;
+    suggestionText: string;
+    suggestionHighlight: string;
+    suggestionCount: string;
+    suggestionCategories: string;
+    suggestionCategory: string;
+    suggestionArrow: string;
+    productsList: string;
+    productCard: string;
+    productCardHover: string;
+    productImage: string;
+    productImagePlaceholder: string;
+    productInfo: string;
+    productTitle: string;
+    productBrand: string;
+    productPrice: string;
+    productComparePrice: string;
+    productDiscount: string;
+    productRating: string;
+    productStock: string;
+    productAddToCart: string;
+    categoriesList: string;
+    categoryItem: string;
+    categoryItemActive: string;
+    categoryIcon: string;
+    categoryLabel: string;
+    categoryCount: string;
+    brandsList: string;
+    brandItem: string;
+    brandLogo: string;
+    brandName: string;
+    recentList: string;
+    recentItem: string;
+    recentIcon: string;
+    recentText: string;
+    recentRemove: string;
+    recentClearAll: string;
+    trendingList: string;
+    trendingItem: string;
+    trendingIcon: string;
+    tabsList: string;
+    tabItem: string;
+    tabItemActive: string;
+    tabCount: string;
+    loading: string;
+    loadingSpinner: string;
+    empty: string;
+    emptyIcon: string;
+    emptyText: string;
+    error: string;
+    errorIcon: string;
+    errorText: string;
+    keyboard: string;
+    keyboardHint: string;
+    keyboardKey: string;
+}
+interface DropdownStyles {
+    root: CSSProperties;
+    container: CSSProperties;
+    header: CSSProperties;
+    content: CSSProperties;
+    footer: CSSProperties;
+    section: CSSProperties;
+    suggestionItem: CSSProperties;
+    productCard: CSSProperties;
+    categoryItem: CSSProperties;
+    brandItem: CSSProperties;
+}
+interface DropdownRef {
+    /** Get currently active/focused index */
+    getActiveIndex: () => number;
+    /** Set active index */
+    setActiveIndex: (index: number) => void;
+    /** Select currently active item */
+    selectActive: () => void;
+    /** Navigate to next item */
+    navigateNext: () => void;
+    /** Navigate to previous item */
+    navigatePrevious: () => void;
+    /** Focus the dropdown */
+    focus: () => void;
+    /** Close the dropdown */
+    close: () => void;
+    /** Get active tab ID (if tabs exist) */
+    getActiveTab?: () => string | null;
+    /** Set active tab */
+    setActiveTab?: (tabId: string) => void;
+    /** Scroll to item */
+    scrollToItem?: (index: number) => void;
 }
-declare function SuggestionsDropdownComposition({ showRecentSearches, showTrending, showTabs, showProducts, placeholder, ...providerProps }: SuggestionsDropdownCompositionProps): React__default.JSX.Element;
 
 /**
- * ImageDisplay – configurable multi-image display (primitive)
+ * ProductCard – one product tile (primitive)
  *
- * Variants: single, carousel, hover, thumbStrip, thumbList. Use in ItemCard,
- * ProductCard, ProductGallery. Overridable via className/style.
+ * Without displayConfig: renders the original minimal layout (image, title, price).
+ * With displayConfig: renders layout variants (minimal, standard, detailed, compact, horizontal).
  */
 
-type ImageDisplayVariant = 'single' | 'carousel' | 'hover' | 'thumbStrip' | 'thumbList';
-interface ImageDisplayProps {
-    images: string[];
-    variant?: ImageDisplayVariant;
-    alt?: string;
+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;
-    carouselAutoplay?: boolean;
-    carouselIntervalMs?: number;
-}
-declare function ImageDisplay({ images, variant, alt, className, style, carouselAutoplay, carouselIntervalMs, }: ImageDisplayProps): React__default.JSX.Element;
+    imageVariant?: ProductCardImageVariant;
+    /** Product display configuration for layout variants */
+    displayConfig?: ProductDisplayConfig;
+    /** Callback when a variant swatch is hovered (e.g., to swap card image) */
+    onVariantHover?: (optionName: string, value: string) => void;
+    /** Callback when a variant swatch is clicked (e.g., to swap card image permanently) */
+    onVariantClick?: (optionName: string, value: string) => void;
+    /** Currently selected variant values (e.g., { Color: 'Black', Size: 'M' }) */
+    selectedVariants?: Record<string, string>;
+    /** Render as link when true and product.url exists */
+    asLink?: boolean;
+    /** Action buttons (add to cart, wishlist, etc.) */
+    actionButtons?: ActionButton[];
+    /** Action buttons position */
+    actionButtonsPosition?: 'overlay-top-right' | 'overlay-bottom' | 'inline';
+    /** Show action button labels */
+    showActionLabels?: boolean;
+    /** Enable image zoom functionality */
+    enableImageZoom?: boolean;
+    /** Image zoom mode: 'hover' (Amazon-style), 'lens', 'click' (lightbox), 'both' (hover + click) */
+    imageZoomMode?: 'hover' | 'lens' | 'click' | 'both';
+    /** Image zoom magnification level (2 = 200%, 3 = 300%) */
+    imageZoomLevel?: number;
+}
+declare function ProductCard({ product, position, section, tabId, onSelect, className, style, imageVariant, displayConfig, onVariantHover, onVariantClick, selectedVariants, asLink, actionButtons, actionButtonsPosition, showActionLabels, enableImageZoom, imageZoomMode, imageZoomLevel, }: ProductCardProps): React__default.JSX.Element;
 
 /**
- * SectionSearchProvider – preset query + filter section
+ * ProductGrid – grid of product cards from context (primitive)
  *
- * 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").
+ * Uses trendingProducts or active tab products; each click calls context selectProduct.
  */
 
-interface RefinementInput {
-    field: string;
-    value: string;
-}
-interface SectionSearchProviderProps {
-    children: React__default.ReactNode;
-    query: string;
-    refinements?: RefinementInput[];
+interface ProductGridProps {
     maxItems?: number;
-    sortBy?: string;
-    enabled?: boolean;
-    sectionId?: string;
+    /** 'trending' | tab id for filtered tab products */
+    source?: 'trending' | string;
+    columns?: number;
+    className?: string;
+    style?: React__default.CSSProperties;
+    gridClassName?: string;
+    /** Product display configuration passed through to each ProductCard */
+    displayConfig?: ProductDisplayConfig;
+    /** Callback when a variant swatch is hovered on a card */
+    onVariantHover?: (optionName: string, value: string) => void;
 }
-declare function SectionSearchProvider({ children, query, refinements, maxItems, sortBy, enabled, sectionId, }: SectionSearchProviderProps): React__default.JSX.Element;
+declare function ProductGrid({ maxItems, source, columns, className, style, gridClassName, displayConfig, onVariantHover, }: ProductGridProps): React__default.JSX.Element | null;
 
 /**
- * SectionSearchContext – preset query/filter section state
+ * CategoriesTabs – horizontal tabs (e.g. filtered tabs) (primitive)
  *
- * For menus, sidebar, front-page blocks. Independent of main search state.
+ * Active tab from context; on select updates context and tracks analytics.
  */
 
-interface SectionSearchContextValue {
-    items: unknown[];
-    loading: boolean;
-    error: Error | null;
-    totalCount: number;
-    sectionId?: string;
-    trackClick: (item: unknown, position: number) => void;
+interface CategoriesTabsProps {
+    className?: string;
+    style?: React__default.CSSProperties;
+    tabClassName?: string;
 }
-declare function useSectionSearchContext(): SectionSearchContextValue;
+declare function CategoriesTabs({ className, style, tabClassName }: CategoriesTabsProps): React__default.JSX.Element | null;
 
 /**
- * SectionItemGrid – generic grid of items from SectionSearchProvider (primitive)
+ * RecentSearchesList – list of recent queries (primitive)
+ *
+ * Reads recentSearches from context; each click calls selectRecentSearch. Optional title/render.
  */
 
-interface SectionItemGridProps {
-    columns?: number;
+interface RecentSearchesListProps {
+    title?: string;
     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;
+    listClassName?: string;
+    renderItem?: (search: RecentSearch, index: number, onSelect: () => void) => React__default.ReactNode;
 }
-declare function SectionItemGrid({ columns, maxItems, className, style, getItemId, getItemTitle, getItemImage, getItemDescription, getItemUrl, renderItem, }: SectionItemGridProps): React__default.JSX.Element;
+declare function RecentSearchesList({ title, maxItems, className, style, listClassName, renderItem, }: RecentSearchesListProps): React__default.JSX.Element | null;
 
 /**
- * SectionLoading – loading state for section (primitive)
+ * TrendingList – list of trending searches (primitive)
+ *
+ * Reads trendingSearches from context; each click calls selectTrendingSearch. Optional title/render.
  */
 
-interface SectionLoadingProps {
+interface TrendingListProps {
+    title?: string;
+    maxItems?: number;
     className?: string;
     style?: React__default.CSSProperties;
-    text?: string;
+    listClassName?: string;
+    renderItem?: (trending: TrendingSearch, index: number, onSelect: () => void) => React__default.ReactNode;
 }
-declare function SectionLoading({ className, style, text }: SectionLoadingProps): React__default.JSX.Element | null;
+declare function TrendingList({ title, maxItems, className, style, listClassName, renderItem, }: TrendingListProps): React__default.JSX.Element | null;
 
 /**
- * SectionError – error state for section (primitive)
+ * SuggestionsLoading – loading indicator (primitive)
  */
 
-interface SectionErrorProps {
+interface SuggestionsLoadingProps {
     className?: string;
     style?: React__default.CSSProperties;
-    render?: (error: Error) => React__default.ReactNode;
+    text?: string;
 }
-declare function SectionError({ className, style, render }: SectionErrorProps): React__default.JSX.Element | null;
+declare function SuggestionsLoading({ className, style, text }: SuggestionsLoadingProps): 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.
+ * SuggestionsError – error message (primitive)
  */
 
-interface ProductGalleryProps {
-    images: string[];
-    variant?: ImageDisplayVariant;
-    alt?: string;
+interface SuggestionsErrorProps {
     className?: string;
     style?: React__default.CSSProperties;
-    carouselAutoplay?: boolean;
-    carouselIntervalMs?: number;
+    render?: (error: Error) => React__default.ReactNode;
 }
-declare function ProductGallery({ images, variant, alt, className, style, carouselAutoplay, carouselIntervalMs, }: ProductGalleryProps): React__default.JSX.Element;
+declare function SuggestionsError({ className, style, render }: SuggestionsErrorProps): React__default.JSX.Element | null;
 
 /**
- * ProductInfo – product detail block (primitive)
+ * SuggestionsDropdownComposition – reference composition
  *
- * Title, description, price, optional variant selector and CTA. Minimal layout;
- * override with className/style. For use on individual product page.
+ * 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 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;
+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 ProductInfo({ title, description, price, currency, renderVariantSelector, renderCTA, className, style, }: ProductInfoProps): React__default.JSX.Element;
+declare function SuggestionsDropdownComposition({ showRecentSearches, showTrending, showTabs, showProducts, placeholder, ...providerProps }: SuggestionsDropdownCompositionProps): React__default.JSX.Element;
 
 /**
- * ProductRecommendations – related / frequently bought (primitive)
+ * ImageZoom – zoom on hover and click (Amazon-style magnifier + lightbox)
  *
- * 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.
+ * Supports three zoom modes:
+ * - hover: Magnified view in a separate panel on the right (Amazon style)
+ * - lens: Magnifying glass that follows cursor
+ * - click: Full-screen lightbox modal
  */
 
-interface ProductRecommendationsProps {
-    title?: string;
-    items: GenericItem[] | unknown[];
-    onItemClick?: (item: unknown, index: number) => void;
-    maxItems?: number;
-    columns?: number;
+type ImageZoomMode = 'hover' | 'lens' | 'click' | 'both';
+interface ImageZoomProps {
+    src: string;
+    alt?: string;
+    mode?: ImageZoomMode;
+    zoomLevel?: number;
     className?: string;
     style?: React__default.CSSProperties;
-    renderItem?: (item: unknown, index: number) => React__default.ReactNode;
+    /** Show zoom indicator icon */
+    showZoomIndicator?: boolean;
+    /** Lens size in pixels (for lens mode) */
+    lensSize?: number;
+    /** Zoom panel size (for hover mode) */
+    zoomPanelSize?: {
+        width: number;
+        height: number;
+    };
+    /** Multiple images for lightbox carousel */
+    images?: string[];
+    /** Current image index (for multi-image support) */
+    currentIndex?: number;
 }
-declare function ProductRecommendations({ title, items, onItemClick, maxItems, columns, className, style, renderItem, }: ProductRecommendationsProps): React__default.JSX.Element | null;
+declare function ImageZoom({ src, alt, mode, zoomLevel, className, style, showZoomIndicator, lensSize, zoomPanelSize, images, currentIndex, }: ImageZoomProps): React__default.JSX.Element;
 
 /**
- * Shared Types for Query Suggestions Components
+ * ImageDisplay – configurable multi-image display (primitive)
  *
- * Data-agnostic types that allow clients to map their own field names
+ * Variants: single, carousel, hover, thumbStrip, thumbList. Use in ItemCard,
+ * ProductCard, ProductGallery. Overridable via className/style.
  */
 
-/** Maps client's data fields to component expected fields */
-interface SuggestionFieldMapping {
-    /** Field path for suggestion text (e.g., "query", "searchTerm", "text") */
-    query: string;
-    /** Field path for suggestion count/popularity */
-    count?: string;
-    /** Field path for object ID */
-    id?: string;
-    /** Field path for categories array */
-    categories?: string;
-    /** Field path for highlighted text */
-    highlighted?: string;
-    /** Custom field mappings */
-    custom?: Record<string, string>;
-}
-/** Maps client's product fields to component expected fields */
-interface ProductFieldMapping {
-    /** Field path for product ID */
-    id: string;
-    /** Field path for product title/name */
-    title: string;
-    /** Field path for product image URL */
-    image?: string;
-    /** Field path for product price */
-    price?: string;
-    /** Field path for original/compare price */
-    comparePrice?: string;
-    /** Field path for product URL */
-    url?: string;
-    /** Field path for brand name */
-    brand?: string;
-    /** Field path for category */
-    category?: string;
-    /** Field path for rating */
-    rating?: string;
-    /** Field path for review count */
-    reviewCount?: string;
-    /** Field path for discount percentage */
-    discount?: string;
-    /** Field path for availability/in stock */
-    inStock?: string;
-    /** Field path for currency */
-    currency?: string;
-    /** Custom field mappings */
-    custom?: Record<string, string>;
-}
-/** Maps client's category/tab fields */
-interface CategoryFieldMapping {
-    id: string;
-    label: string;
-    count?: string;
-    icon?: string;
-    image?: string;
-}
-/** Maps client's brand fields */
-interface BrandFieldMapping {
-    id?: string;
-    name: string;
-    logo?: string;
-    count?: string;
-}
-type DropdownLayout = 'list' | 'two-column' | 'three-column' | 'grid' | 'hero' | 'full-width' | 'mobile-sheet' | 'overlay';
-type ProductCardSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
-type ProductCardStyle = 'minimal' | 'standard' | 'detailed' | 'compact' | 'horizontal';
-/** Available dropdown variants */
-type SuggestionDropdownVariant$1 = 'amazon' | 'google' | 'pinterest' | 'spotlight' | 'shopify' | 'mobile-sheet' | 'minimal';
-interface VisualConfig {
-    /** Overall dropdown layout */
-    layout?: DropdownLayout;
-    /** Show/hide shadows */
-    shadows?: boolean;
-    /** Border radius (px or CSS value) */
-    borderRadius?: number | string;
-    /** Animation style */
-    animation?: 'none' | 'fade' | 'slide' | 'scale' | 'spring';
-    /** Animation duration in ms */
-    animationDuration?: number;
-    /** Blur background when open */
-    backdropBlur?: boolean;
-    /** Show dividers between sections */
-    showDividers?: boolean;
-    /** Compact mode (reduced padding) */
-    compact?: boolean;
-}
-type SectionType = 'suggestions' | 'recent' | 'trending' | 'products' | 'categories' | 'brands' | 'collections' | 'pages' | 'custom';
-interface SectionConfig {
-    /** Section identifier */
-    id: SectionType | string;
-    /** Section title (can be ReactNode for custom rendering) */
-    title?: string | ReactNode;
-    /** Whether section is enabled */
-    enabled?: boolean;
-    /** Maximum items to show */
-    maxItems?: number;
-    /** Section display order (lower = higher) */
-    order?: number;
-    /** Section-specific layout override */
-    layout?: 'list' | 'grid' | 'horizontal-scroll' | 'chips';
-    /** Number of columns for grid layout */
-    columns?: number;
-    /** Show "View All" link */
-    showViewAll?: boolean;
-    /** View All link URL or handler */
-    viewAllLink?: string;
-    /** Custom CSS class */
+type ImageDisplayVariant = 'single' | 'carousel' | 'hover' | 'thumbStrip' | 'thumbList';
+interface ImageDisplayProps {
+    images: string[];
+    variant?: ImageDisplayVariant;
+    alt?: string;
     className?: string;
-    /** Custom styles */
-    style?: CSSProperties;
-    /** Custom renderer for entire section */
-    render?: (data: any[], config: SectionConfig) => ReactNode;
-    /** Custom renderer for individual items */
-    renderItem?: (item: any, index: number) => ReactNode;
-    /** Empty state message */
-    emptyMessage?: string;
-    /** Icon for section header */
-    icon?: ReactNode;
-}
-interface ProductDisplayConfig {
-    /** Card size */
-    size?: ProductCardSize;
-    /** Card style */
-    style?: ProductCardStyle;
-    /** Show product image */
-    showImage?: boolean;
-    /** Image aspect ratio */
-    imageAspectRatio?: '1:1' | '4:3' | '3:4' | '16:9' | 'auto';
-    /** Show price */
-    showPrice?: boolean;
-    /** Show compare/original price */
-    showComparePrice?: boolean;
-    /** Show discount badge */
-    showDiscount?: boolean;
-    /** Show brand */
-    showBrand?: boolean;
-    /** Show rating */
-    showRating?: boolean;
-    /** Show stock status */
-    showStock?: boolean;
-    /** Show add to cart button */
-    showAddToCart?: boolean;
-    /** Currency symbol */
-    currency?: string;
-    /** Currency position */
-    currencyPosition?: 'before' | 'after';
-    /** Decimal places for price */
-    priceDecimals?: number;
-    /** Truncate title after N lines */
-    titleLines?: number;
-    /** Hover effect */
-    hoverEffect?: 'none' | 'lift' | 'glow' | 'scale' | 'border';
-    /** Image placeholder */
-    imagePlaceholder?: ReactNode;
-    /** Lazy load images */
-    lazyLoadImages?: boolean;
-}
-interface SuggestionDisplayConfig {
-    /** Show search icon */
-    showIcon?: boolean;
-    /** Custom icon */
-    icon?: ReactNode;
-    /** Show hit count */
-    showCount?: boolean;
-    /** Show categories inline */
-    showCategories?: boolean;
-    /** Max categories to show */
-    maxCategories?: number;
-    /** Highlight matching text */
-    highlightMatches?: boolean;
-    /** Highlight style */
-    highlightStyle?: CSSProperties;
-    /** Show arrow on hover */
-    showArrow?: boolean;
-    /** Category click behavior */
-    categoryClickable?: boolean;
+    style?: React__default.CSSProperties;
+    carouselAutoplay?: boolean;
+    carouselIntervalMs?: number;
+    /** Enable zoom functionality */
+    enableZoom?: boolean;
+    /** Zoom mode: 'hover' (Amazon-style), 'lens', 'click' (lightbox), 'both' (hover + click) */
+    zoomMode?: ImageZoomMode;
+    /** Zoom magnification level (2 = 200%, 3 = 300%) */
+    zoomLevel?: number;
+    /** Show navigation dots for carousel */
+    showDots?: boolean;
 }
-interface DropdownThemeConfig {
-    /** Light/dark mode */
-    mode?: 'light' | 'dark' | 'auto';
-    /** Primary brand color */
-    primaryColor?: string;
-    /** Background color */
-    backgroundColor?: string;
-    /** Surface color (cards, sections) */
-    surfaceColor?: string;
-    /** Text color */
+declare function ImageDisplay({ images, variant, alt, className, style, carouselAutoplay, carouselIntervalMs, enableZoom, zoomMode, zoomLevel, showDots, }: ImageDisplayProps): React__default.JSX.Element;
+
+/**
+ * PriceDisplay – reusable price display primitive
+ *
+ * Handles single price, compare price with strikethrough, discount percentage,
+ * and price range display.
+ */
+
+interface PriceDisplayProps {
+    price?: number;
+    comparePrice?: number;
+    priceRange?: PriceRange | null;
+    currency?: string;
+    currencyPosition?: 'before' | 'after';
+    priceDecimals?: number;
+    showDiscount?: boolean;
+    className?: string;
+    style?: React__default.CSSProperties;
+}
+declare function PriceDisplay({ price, comparePrice, priceRange, currency, currencyPosition, priceDecimals, showDiscount, className, style, }: PriceDisplayProps): React__default.JSX.Element | null;
+
+/**
+ * BadgeList – renders product badges (sale, new, sold out, custom)
+ */
+
+interface BadgeListProps {
+    badges: ProductBadge[];
+    maxBadges?: number;
+    position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'inline';
+    className?: string;
+    style?: React__default.CSSProperties;
+}
+declare function BadgeList({ badges, maxBadges, position, className, style, }: BadgeListProps): React__default.JSX.Element | null;
+
+/**
+ * RatingDisplay – star rating display with review count
+ *
+ * Supports multiple variants: stars-only, compact, full, inline.
+ * Can be read-only (display) or interactive (for reviews).
+ */
+
+type RatingVariant = 'stars-only' | 'compact' | 'full' | 'inline';
+type RatingSize = 'small' | 'medium' | 'large';
+interface RatingDisplayProps {
+    /** Rating value (0-5) */
+    rating: number;
+    /** Total number of reviews */
+    reviewCount?: number;
+    /** Display variant */
+    variant?: RatingVariant;
+    /** Size of stars */
+    size?: RatingSize;
+    /** Maximum rating (default: 5) */
+    maxRating?: number;
+    /** Show decimal rating number */
+    showNumeric?: boolean;
+    /** Show half stars */
+    showHalfStars?: boolean;
+    /** Interactive mode (for leaving reviews) */
+    interactive?: boolean;
+    /** Callback when rating is clicked (interactive mode) */
+    onRatingChange?: (rating: number) => void;
+    /** Custom star color */
+    starColor?: string;
+    /** Custom empty star color */
+    emptyStarColor?: string;
+    /** Custom text color */
     textColor?: string;
-    /** Secondary text color */
-    textSecondaryColor?: string;
-    /** Border color */
-    borderColor?: string;
-    /** Hover background */
-    hoverColor?: string;
-    /** Highlight/match color */
-    highlightColor?: string;
-    /** Success color (in stock, etc.) */
-    successColor?: string;
-    /** Error color (out of stock, etc.) */
-    errorColor?: string;
-    /** Font family */
-    fontFamily?: string;
-    /** Base font size */
-    fontSize?: number | string;
-    /** Border radius */
-    borderRadius?: number | string;
-    /** Box shadow */
-    boxShadow?: string;
-    /** Custom CSS variables */
-    cssVariables?: Record<string, string>;
+    /** Show review count in parentheses */
+    showReviewCount?: boolean;
+    /** Custom review count format */
+    reviewCountFormat?: (count: number) => string;
+    className?: string;
+    style?: React__default.CSSProperties;
 }
-interface AnalyticsConfig {
-    /** Enable analytics */
-    enabled?: boolean;
-    /** Track suggestion clicks */
-    trackSuggestionClicks?: boolean;
-    /** Track product clicks */
-    trackProductClicks?: boolean;
-    /** Track impressions */
-    trackImpressions?: boolean;
-    /** Impression debounce time (ms) */
-    impressionDebounce?: number;
-    /** Track category clicks */
-    trackCategoryClicks?: boolean;
-    /** Track brand clicks */
-    trackBrandClicks?: boolean;
-    /** Track search submissions */
-    trackSearchSubmit?: boolean;
-    /** Custom analytics tags */
-    tags?: string[];
-    /** User ID for personalization */
-    userId?: string;
-    /** Session ID */
-    sessionId?: string;
-    /** Custom event handler */
-    onEvent?: (eventType: string, data: any) => void;
+declare function RatingDisplay({ rating, reviewCount, variant, size, maxRating, showNumeric, showHalfStars, interactive, onRatingChange, starColor, emptyStarColor, textColor, showReviewCount, reviewCountFormat, className, style, }: RatingDisplayProps): React__default.JSX.Element | null;
+
+/**
+ * VariantSwatches – inline variant indicators for card display
+ *
+ * Shows color dots, size labels, and "+N more" overflow for compact card views.
+ */
+
+interface VariantSwatchesProps {
+    options: ProductOption[];
+    /** Which option names to show (default: all) */
+    visibleOptions?: string[];
+    /** Max values per option before "+N more" (default: 5) */
+    maxValues?: number;
+    /** Map option value names to CSS color strings */
+    colorMap?: Record<string, string>;
+    /** Currently selected value per option (e.g., { Color: 'Black', Size: 'M' }) */
+    selectedValues?: Record<string, string>;
+    /** Product variants for availability checking */
+    variants?: ProductVariant[];
+    /** Show availability cross-out for unavailable combos (default: true) */
+    showAvailability?: boolean;
+    onSwatchHover?: (optionName: string, value: string) => void;
+    onSwatchClick?: (optionName: string, value: string) => void;
+    className?: string;
+    style?: React__default.CSSProperties;
 }
-interface DropdownEventHandlers<TSuggestion = any, TProduct = any, TCategory = any, TBrand = any> {
-    /** Suggestion selected */
-    onSuggestionSelect?: (suggestion: TSuggestion, index: number) => void;
-    /** Product clicked */
-    onProductClick?: (product: TProduct, index: number) => void;
-    /** Category clicked */
-    onCategoryClick?: (category: TCategory, suggestion?: TSuggestion) => void;
-    /** Brand clicked */
-    onBrandClick?: (brand: TBrand) => void;
-    /** Tab/filter changed */
-    onTabChange?: (tabId: string, tab?: any) => void;
-    /** Recent search clicked */
-    onRecentClick?: (query: string) => void;
-    /** Recent search removed */
-    onRecentRemove?: (query: string) => void;
-    /** Clear all recent searches */
-    onRecentClearAll?: () => void;
-    /** View all clicked */
-    onViewAll?: (section: SectionType | string) => void;
-    /** Search submitted */
-    onSearchSubmit?: (query: string) => void;
-    /** Dropdown opened */
-    onOpen?: () => void;
-    /** Dropdown closed */
-    onClose?: () => void;
-    /** Keyboard navigation */
-    onNavigate?: (direction: 'up' | 'down' | 'left' | 'right', index: number) => void;
-    /** Add to cart clicked (if enabled) */
-    onAddToCart?: (product: TProduct) => void;
+declare function VariantSwatches({ options, visibleOptions, maxValues, colorMap, selectedValues, variants, showAvailability, onSwatchHover, onSwatchClick, className, style, }: VariantSwatchesProps): React__default.JSX.Element | null;
+
+/**
+ * VariantSelector – full variant selector for product detail pages
+ *
+ * Three render modes per option:
+ * - swatch: color circles (auto-detected for "Color" option or when colorMap provided)
+ * - button: rectangular buttons (default for most options)
+ * - dropdown: <select> for options with many values
+ */
+
+interface VariantSelectorProps {
+    options: ProductOption[];
+    variants: ProductVariant[];
+    selections: Record<string, string>;
+    onSelectionChange: (optionName: string, value: string) => void;
+    /** Override render mode per option name */
+    optionRenderModes?: Record<string, 'swatch' | 'button' | 'dropdown'>;
+    /** Auto-switch to dropdown when values exceed this count (default: 8) */
+    dropdownThreshold?: number;
+    /** Map value names to CSS colors */
+    colorMap?: Record<string, string>;
+    /** Show availability cross-out for unavailable combos */
+    showAvailability?: boolean;
+    /** Currently matched variant (for display) */
+    selectedVariant?: ProductVariant | null;
+    className?: string;
+    style?: React__default.CSSProperties;
 }
-interface AccessibilityConfig {
-    /** ARIA label for dropdown */
-    ariaLabel?: string;
-    /** ARIA labelledby */
-    ariaLabelledBy?: string;
-    /** Announce selection to screen readers */
-    announceSelection?: boolean;
-    /** Custom announcement text */
-    getAnnouncementText?: (item: any, type: string) => string;
-    /** Keyboard navigation enabled */
-    keyboardNavigation?: boolean;
-    /** Focus trap (keep focus within dropdown) */
-    focusTrap?: boolean;
-    /** Auto focus first item */
-    autoFocus?: boolean;
-    /** Close on escape */
-    closeOnEscape?: boolean;
-    /** Close on click outside */
-    closeOnClickOutside?: boolean;
+declare function VariantSelector({ options, variants, selections, onSelectionChange, optionRenderModes, dropdownThreshold, colorMap, showAvailability, selectedVariant: _selectedVariant, className, style, }: VariantSelectorProps): React__default.JSX.Element | null;
+
+/**
+ * withAnalytics – HOC that wraps any React component to inject analytics tracking
+ */
+
+interface WithAnalyticsConfig {
+    /** Track clicks on the component */
+    trackClick?: boolean;
+    /** Track impressions (visibility) */
+    trackImpression?: boolean;
+    /** Custom event name for click */
+    clickEventName?: string;
+    /** Extract product/item data from props */
+    getProductFromProps?: (props: any) => ProductItem | null;
+    /** Extract position from props */
+    getPositionFromProps?: (props: any) => number;
 }
-interface BaseDropdownProps<TSuggestion = any, TProduct = any, TCategory = any, TBrand = any> extends DropdownEventHandlers<TSuggestion, TProduct, TCategory, TBrand> {
-    /** Current search query */
+interface WithAnalyticsInjectedProps {
+    seekoraClient?: SeekoraClient;
+    seekoraContext?: SearchContext | Partial<SearchContext>;
+}
+declare function withAnalytics<P extends object>(Component: React__default.ComponentType<P>, config?: WithAnalyticsConfig): React__default.ComponentType<P & WithAnalyticsInjectedProps>;
+
+/**
+ * AnalyticsProvider – context + delegated event listener for data-seekora-* attribute-based analytics
+ *
+ * Installs a delegated click listener on a container. Any descendant with
+ * data-seekora-track="click"|"add-to-cart" and data-seekora-product-id="..."
+ * automatically fires analytics events without React wiring.
+ */
+
+interface AnalyticsProviderProps {
+    client: SeekoraClient;
+    context?: SearchContext | Partial<SearchContext>;
+    children: React__default.ReactNode;
+}
+interface AnalyticsContextValue {
+    client: SeekoraClient;
+    context?: SearchContext | Partial<SearchContext>;
+}
+declare const useAnalyticsProvider: () => AnalyticsContextValue | null;
+declare function AnalyticsProvider({ client, context, children }: AnalyticsProviderProps): 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;
-    /** Whether dropdown is open/visible */
-    isOpen?: boolean;
-    /** Loading state */
-    loading?: boolean;
-    /** Error state */
-    error?: Error | string | null;
-    /** Suggestion items */
-    suggestions?: TSuggestion[];
-    /** Product items */
-    products?: TProduct[];
-    /** Category/filter tabs */
-    categories?: TCategory[];
-    /** Brand items */
-    brands?: TBrand[];
-    /** Recent searches (strings or objects) */
-    recentSearches?: string[] | Array<{
-        query: string;
-        timestamp?: number;
-    }>;
-    /** Trending searches */
-    trendingSearches?: string[] | TSuggestion[];
-    /** Filtered tabs with products */
-    filteredTabs?: Array<{
-        id: string;
-        label: string;
-        products?: TProduct[];
-        nb_hits?: number;
-        filter?: string;
-    }>;
-    /** Currently active tab ID */
-    activeTab?: string;
-    /** Map suggestion data fields */
-    suggestionFields?: SuggestionFieldMapping;
-    /** Map product data fields */
-    productFields?: ProductFieldMapping;
-    /** Map category data fields */
-    categoryFields?: CategoryFieldMapping;
-    /** Map brand data fields */
-    brandFields?: BrandFieldMapping;
-    /** Section configurations */
-    sections?: SectionConfig[];
-    /** Product display config */
-    productDisplay?: ProductDisplayConfig;
-    /** Suggestion display config */
-    suggestionDisplay?: SuggestionDisplayConfig;
-    /** Visual/layout config */
-    visual?: VisualConfig;
-    /** Theme config */
-    theme?: DropdownThemeConfig;
-    /** Analytics config */
-    analytics?: AnalyticsConfig;
-    /** Accessibility config */
-    accessibility?: AccessibilityConfig;
-    /** Dropdown width */
-    width?: string | number;
-    /** Dropdown max height */
-    maxHeight?: string | number;
-    /** Dropdown min height */
-    minHeight?: string | number;
-    /** Z-index */
-    zIndex?: number;
-    /** Root CSS class */
+    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;
-    /** Root inline styles */
-    style?: CSSProperties;
-    /** CSS classes for parts */
-    classNames?: Partial<DropdownClassNames>;
-    /** Inline styles for parts */
-    styles?: Partial<DropdownStyles>;
-    /** Custom header */
-    header?: ReactNode;
-    /** Custom footer */
-    footer?: ReactNode;
-    /** Custom loading state */
-    renderLoading?: () => ReactNode;
-    /** Custom empty state */
-    renderEmpty?: (query: string) => ReactNode;
-    /** Custom error state */
-    renderError?: (error: Error | string) => ReactNode;
-    /** Reference to input element (for focus management) */
-    inputRef?: React.RefObject<HTMLInputElement>;
+    style?: React__default.CSSProperties;
+    /** Show loading state when fetching and no previous items (default false: show previous results until new render) */
+    showLoadingState?: boolean;
+    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;
 }
-interface DropdownClassNames {
-    root: string;
-    container: string;
-    header: string;
-    content: string;
-    footer: string;
-    section: string;
-    sectionHeader: string;
-    sectionTitle: string;
-    sectionContent: string;
-    sectionViewAll: string;
-    suggestionsList: string;
-    suggestionItem: string;
-    suggestionItemActive: string;
-    suggestionIcon: string;
-    suggestionText: string;
-    suggestionHighlight: string;
-    suggestionCount: string;
-    suggestionCategories: string;
-    suggestionCategory: string;
-    suggestionArrow: string;
-    productsList: string;
-    productCard: string;
-    productCardHover: string;
-    productImage: string;
-    productImagePlaceholder: string;
-    productInfo: string;
-    productTitle: string;
-    productBrand: string;
-    productPrice: string;
-    productComparePrice: string;
-    productDiscount: string;
-    productRating: string;
-    productStock: string;
-    productAddToCart: string;
-    categoriesList: string;
-    categoryItem: string;
-    categoryItemActive: string;
-    categoryIcon: string;
-    categoryLabel: string;
-    categoryCount: string;
-    brandsList: string;
-    brandItem: string;
-    brandLogo: string;
-    brandName: string;
-    recentList: string;
-    recentItem: string;
-    recentIcon: string;
-    recentText: string;
-    recentRemove: string;
-    recentClearAll: string;
-    trendingList: string;
-    trendingItem: string;
-    trendingIcon: string;
-    tabsList: string;
-    tabItem: string;
-    tabItemActive: string;
-    tabCount: string;
-    loading: string;
-    loadingSpinner: string;
-    empty: string;
-    emptyIcon: string;
-    emptyText: string;
-    error: string;
-    errorIcon: string;
-    errorText: string;
-    keyboard: string;
-    keyboardHint: string;
-    keyboardKey: string;
+declare function SectionItemGrid({ columns, maxItems, className, style, showLoadingState, 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;
 }
-interface DropdownStyles {
-    root: CSSProperties;
-    container: CSSProperties;
-    header: CSSProperties;
-    content: CSSProperties;
-    footer: CSSProperties;
-    section: CSSProperties;
-    suggestionItem: CSSProperties;
-    productCard: CSSProperties;
-    categoryItem: CSSProperties;
-    brandItem: CSSProperties;
+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;
 }
-interface DropdownRef {
-    /** Get currently active/focused index */
-    getActiveIndex: () => number;
-    /** Set active index */
-    setActiveIndex: (index: number) => void;
-    /** Select currently active item */
-    selectActive: () => void;
-    /** Navigate to next item */
-    navigateNext: () => void;
-    /** Navigate to previous item */
-    navigatePrevious: () => void;
-    /** Focus the dropdown */
-    focus: () => void;
-    /** Close the dropdown */
-    close: () => void;
-    /** Get active tab ID (if tabs exist) */
-    getActiveTab?: () => string | null;
-    /** Set active tab */
-    setActiveTab?: (tabId: string) => void;
-    /** Scroll to item */
-    scrollToItem?: (index: number) => void;
+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.
+ *
+ * When options/variants/selections/onSelectionChange are provided and
+ * renderVariantSelector is NOT provided, renders the built-in VariantSelector.
+ * renderVariantSelector still takes priority as an override.
+ */
+
+interface ProductInfoProps {
+    title: string;
+    description?: string;
+    price?: number | string;
+    currency?: string;
+    /** Compare/original price for strikethrough display */
+    comparePrice?: number | string;
+    /** Product brand */
+    brand?: string;
+    /** Whether product is available */
+    available?: boolean;
+    /** Badges to display */
+    badges?: ProductBadge[];
+    /** Product option axes (Color, Size, etc.) */
+    options?: ProductOption[];
+    /** Product variants */
+    variants?: ProductVariant[];
+    /** Currently selected variant */
+    selectedVariant?: ProductVariant | null;
+    /** Current option selections */
+    selections?: Record<string, string>;
+    /** Called when an option value is selected */
+    onSelectionChange?: (optionName: string, value: string) => void;
+    /** Optional variant selector override (takes priority over built-in) */
+    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, comparePrice, brand, available, badges, options, variants, selectedVariant: _selectedVariant, selections, onSelectionChange, 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;
 
 /**
  * MinimalDropdown - Ultra-Clean Minimalist Style
@@ -2805,6 +3150,12 @@ declare const extractProduct: (item: any, mapping?: ProductFieldMapping) => {
     discount: any;
     inStock: any;
     currency: any;
+    images: any;
+    originalPrice: any;
+    available: any;
+    options: any;
+    variants: any;
+    tags: any;
     _raw: any;
 };
 /**
@@ -2840,6 +3191,36 @@ declare const highlightText: (text: string, query: string, options?: {
     className?: string;
     style?: CSSProperties;
 }) => string;
+/**
+ * Extract badges from product tags (Shopify convention: "badge:new", "badge:limited")
+ * and auto-generate sale/soldOut badges from product data.
+ */
+declare const extractBadges: (tags?: string[], product?: {
+    price?: number;
+    original_price?: number;
+    compare_at_price?: number;
+    available?: boolean;
+}) => ProductBadge[];
+/**
+ * Compute min/max price from variants. Returns null if all variants have the same price.
+ */
+declare const getPriceRange: (variants?: ProductVariant[]) => PriceRange | null;
+/**
+ * Format a price range like "$54.00 - $72.00"
+ */
+declare const formatPriceRange: (range: PriceRange, config?: Pick<ProductDisplayConfig, "currency" | "currencyPosition" | "priceDecimals">) => string;
+/**
+ * Given current selections, return which values for an option are still available
+ * based on variant availability.
+ */
+declare const getAvailableValuesForOption: (optionName: string, options: ProductOption[], variants: ProductVariant[], selections: Record<string, string>) => {
+    value: string;
+    available: boolean;
+}[];
+/**
+ * Find the exact variant matching all selected options.
+ */
+declare const findVariantBySelections: (options: ProductOption[], variants: ProductVariant[], selections: Record<string, string>) => ProductVariant | null;
 declare const getRecentSearches: (storeId?: string) => string[];
 declare const addRecentSearch: (query: string, storeId?: string) => string[];
 declare const removeRecentSearch: (query: string, storeId?: string) => string[];
@@ -3523,6 +3904,82 @@ declare function useNaturalLanguageFilters(options?: NaturalLanguageFiltersOptio
  */
 declare function formatParsedFilters(filters: ParsedFilter[]): string;
 
+/**
+ * useVariantSelection – manages variant selection state
+ *
+ * Single source of truth for variant interactions on product pages.
+ * Cards display variants passively; product pages use this hook.
+ */
+
+interface UseVariantSelectionOptions {
+    options?: ProductOption[];
+    variants?: ProductVariant[];
+    initialSelections?: Record<string, string>;
+    onVariantChange?: (variant: ProductVariant | null, selections: Record<string, string>) => void;
+}
+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;
+}
+declare function useVariantSelection({ options, variants, initialSelections, onVariantChange, }?: UseVariantSelectionOptions): UseVariantSelectionReturn;
+
+/**
+ * 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.
+ */
+
+interface UseProductAnalyticsOptions {
+    client: SeekoraClient;
+    product: ProductItem;
+    position?: number;
+    section?: string;
+    tabId?: string;
+    query?: string;
+    context?: SearchContext | Partial<SearchContext>;
+    enabled?: boolean;
+}
+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;
+}
+declare function useProductAnalytics({ client, product, position, section, tabId, query, context, enabled, }: UseProductAnalyticsOptions): UseProductAnalyticsReturn;
+
 /**
  * Default Theme
  */
@@ -3660,5 +4117,5 @@ declare function updateSuggestionsStyles(theme: SuggestionsThemeVariables): void
 
 declare const createTheme: (config: ThemeConfig) => _seekora_ai_ui_sdk_types.Theme;
 
-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, parseHighlightMarkup, 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, HighlightMarkupOptions, 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 };
+export { ActionButtons, AmazonDropdown, AnalyticsProvider, BadgeList, Breadcrumb, CategoriesTabs, ClearRefinements, CurrentRefinements, DocSearch, DocSearchButton, DropdownPanel, Facets, FederatedDropdown, FrequentlyBoughtTogether, GoogleDropdown, HierarchicalMenu, Highlight, HitsPerPage, ImageDisplay, ImageZoom, InfiniteHits, ItemCard, ItemGrid, MinimalDropdown, MobileFilters, MobileFiltersButton, MobileSheetDropdown, Pagination, PinterestDropdown, PriceDisplay, ProductCard, ProductGallery, ProductGrid, ProductInfo, ProductRecommendations, QuerySuggestions, QuerySuggestionsDropdown, RangeInput, RangeSlider, RatingDisplay, 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, VariantSelector, VariantSwatches, addRecentSearch, addToRecentlyViewed, brandPresets, breakpoints, clearRecentSearches, clearSuggestionsCache, createSuggestionsCache, createSuggestionsTheme, createTheme, darkTheme, darkThemeVariables, defaultTheme, extractBadges, extractBrand, extractCategory, extractProduct, extractSuggestion, findVariantBySelections, formatParsedFilters, formatPriceRange, formatPrice as formatSuggestionPrice, generateSuggestionsStylesheet, getAvailableValuesForOption, getPriceRange, getRecentSearches, getShortcutText, getSuggestionsCache, highlightText, injectGlobalResponsiveStyles, injectSuggestionsStyles, lightThemeVariables, mediaQueries, minimalTheme, minimalThemeVariables, parseHighlightMarkup, removeRecentSearch, touchTargets, updateSuggestionsStyles, useAnalytics, useAnalyticsProvider, useDocSearch, useSeekoraSearch$1 as useDocSearchSeekoraSearch, useInjectResponsiveStyles, useKeyboard, useNaturalLanguageFilters, useProductAnalytics, useQuerySuggestions, useQuerySuggestionsEnhanced, useResponsive, useSearchContext, useSearchState, useSectionSearchContext, useSeekoraSearch, useSmartSuggestions, useSuggestionsAnalytics, useSuggestionsContext, useVariantSelection, withAnalytics };
+export type { ActionButton, ActionButtonType, ActionButtonsProps, AnalyticsConfig, AnalyticsEventPayload, AnalyticsProviderProps, BadgeListProps, 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, HighlightMarkupOptions, HighlightProps, HighlightTheme, HitsPerPageItem, HitsPerPageProps, HitsPerPageTheme, ImageDisplayProps, ImageDisplayVariant, ImageZoomMode, ImageZoomProps, InfiniteHitsProps, InfiniteHitsTheme, ImageDisplayVariant$1 as ItemCardImageVariant, ItemCardProps, ItemGridProps, MobileFiltersButtonProps, MobileFiltersProps, MobileFiltersTheme, NaturalLanguageFiltersOptions, NaturalLanguageResult, NavigableItem, ParsedFilter, PriceDisplayProps, ProductCardImageVariant, ProductCardProps, ProductClickEventData, ProductDisplayConfig, ProductFieldMapping, ProductGalleryProps, ProductGridProps, ProductInfoProps, ProductRecommendationsProps, QuerySuggestionsDropdownProps, QuerySuggestionsDropdownRef, QuerySuggestionsProps, QuerySuggestionsTheme, RangeSliderProps, RangeSliderTheme, RatingDisplayProps, RatingSize, RatingVariant, 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, UseProductAnalyticsOptions, UseProductAnalyticsReturn, UseQuerySuggestionsEnhancedOptions, UseQuerySuggestionsEnhancedReturn, UseSmartSuggestionsReturn, UseSuggestionsAnalyticsOptions, UseSuggestionsAnalyticsReturn, UseVariantSelectionOptions, UseVariantSelectionReturn, VariantSelectorProps, VariantSwatchesProps, WithAnalyticsConfig, WithAnalyticsInjectedProps };