@seekora-ai/ui-sdk-react 0.2.12 → 0.2.14

package/dist/components/suggestions-primitives/SuggestionList.js

@@ -8,21 +8,24 @@
 import React from 'react';
 import { useSuggestionsContext } from './SuggestionsContext';
 import { SuggestionItem } from './SuggestionItem';
-import { SuggestionsLoading } from './SuggestionsLoading';
 import { clsx } from 'clsx';
 const listStyle = {
     margin: 0,
     padding: '4px 0',
 };
-export function SuggestionList({ maxItems = 10, className, style, listClassName, enableHighlightMarkup = true, highlightMarkupOptions, renderItem, }) {
+export function SuggestionList({ maxItems = 10, className, style, listClassName, showLoadingState = false, renderLoading, enableHighlightMarkup = true, highlightMarkupOptions, renderItem, }) {
     const { suggestions, activeIndex, loading, selectSuggestion, getAllNavigableItems, } = useSuggestionsContext();
     const items = suggestions.slice(0, maxItems);
     const navigableItems = getAllNavigableItems();
     const suggestionStartIndex = navigableItems.findIndex((n) => n.type === 'suggestion');
     const activeIsInSuggestions = suggestionStartIndex >= 0 && activeIndex >= suggestionStartIndex && activeIndex < suggestionStartIndex + items.length;
-    if (loading) {
-        return React.createElement(SuggestionsLoading, { className: className, style: style });
+    // When loading with no previous results, show loading only if showLoadingState (default: don't show loading screen)
+    if (loading && items.length === 0 && showLoadingState) {
+        if (renderLoading)
+            return React.createElement(React.Fragment, null, renderLoading());
+        return (React.createElement("div", { className: clsx('seekora-suggestions-loading', className), style: { padding: 16, color: 'var(--seekora-text-secondary, #6b7280)', fontSize: '0.875rem', ...style } }, "Loading..."));
     }
+    // When loading with previous results, show previous results (no loading UI)
     if (items.length === 0)
         return null;
     return (React.createElement("div", { className: clsx('seekora-suggestions-list', className), style: style },

package/dist/components/suggestions-primitives/SuggestionsDropdownComposition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SuggestionsDropdownComposition.d.ts","sourceRoot":"","sources":["../../../src/components/suggestions-primitives/SuggestionsDropdownComposition.tsx"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAW1B,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAEtE,MAAM,WAAW,mCAAoC,SAAQ,IAAI,CAAC,wBAAwB,EAAE,UAAU,CAAC;IACrG,+CAA+C;IAC/C,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,yBAAyB;IACzB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,oCAAoC;IACpC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,wBAAwB;IACxB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,8BAA8B;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,8BAA8B,CAAC,EAC7C,kBAAyB,EACzB,YAAmB,EACnB,QAAe,EACf,YAAmB,EACnB,WAAW,EACX,GAAG,aAAa,EACjB,EAAE,mCAAmC,qBAiBrC"}
+{"version":3,"file":"SuggestionsDropdownComposition.d.ts","sourceRoot":"","sources":["../../../src/components/suggestions-primitives/SuggestionsDropdownComposition.tsx"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAU1B,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAEtE,MAAM,WAAW,mCAAoC,SAAQ,IAAI,CAAC,wBAAwB,EAAE,UAAU,CAAC;IACrG,+CAA+C;IAC/C,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,yBAAyB;IACzB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,oCAAoC;IACpC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,wBAAwB;IACxB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,8BAA8B;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,8BAA8B,CAAC,EAC7C,kBAAyB,EACzB,YAAmB,EACnB,QAAe,EACf,YAAmB,EACnB,WAAW,EACX,GAAG,aAAa,EACjB,EAAE,mCAAmC,qBAgBrC"}

package/dist/components/suggestions-primitives/SuggestionsDropdownComposition.js

@@ -15,7 +15,6 @@ import { SuggestionList } from './SuggestionList';
 import { CategoriesTabs } from './CategoriesTabs';
 import { ProductGrid } from './ProductGrid';
 import { TrendingList } from './TrendingList';
-import { SuggestionsLoading } from './SuggestionsLoading';
 import { SuggestionsError } from './SuggestionsError';
 export function SuggestionsDropdownComposition({ showRecentSearches = true, showTrending = true, showTabs = true, showProducts = true, placeholder, ...providerProps }) {
     return (React.createElement(SuggestionsProvider, { ...providerProps },
@@ -23,7 +22,6 @@ export function SuggestionsDropdownComposition({ showRecentSearches = true, show
             React.createElement(SearchInput, { placeholder: placeholder }),
             React.createElement(DropdownPanel, null,
                 React.createElement(SuggestionsError, null),
-                React.createElement(SuggestionsLoading, null),
                 showRecentSearches ? React.createElement(RecentSearchesList, null) : null,
                 React.createElement(SuggestionList, null),
                 showTabs ? React.createElement(CategoriesTabs, null) : null,

package/dist/components/suggestions-primitives/highlightMarkup.d.ts

@@ -1,18 +1,30 @@
 /**
  * Parses suggestion text containing <mark>...</mark> and returns React nodes
- * with the marked segments rendered as <mark> elements. Safe: inner content
+ * with the marked segments rendered as styled elements. Safe: inner content
  * is rendered as text, not HTML.
  */
 import React from 'react';
+/** Visual highlight styles */
+export type HighlightStyle = 'background' | 'underline' | 'bold' | 'color-only';
 export interface HighlightMarkupOptions {
-    /** Class name for the <mark> element. */
+    /** Class name for the highlight element. */
     markClassName?: string;
-    /** Inline style for the <mark> element. */
+    /** Inline style for the highlight element (merged with computed styles). */
     markStyle?: React.CSSProperties;
+    /** Override background color for highlighted segments */
+    highlightColor?: string;
+    /** Text color for highlighted segments */
+    highlightTextColor?: string;
+    /** Font weight for highlighted segments */
+    highlightFontWeight?: string | number;
+    /** Visual highlight style (default: 'background') */
+    highlightStyle?: HighlightStyle;
+    /** Which HTML element to render for highlights (default: 'mark') */
+    highlightTag?: keyof JSX.IntrinsicElements;
 }
 /**
  * Converts a string like "lined <mark>blue</mark>" into React nodes with
- * the marked part rendered as a <mark> element. When no <mark> tags are
+ * the marked part rendered as a styled element. When no <mark> tags are
  * present, returns the string as-is.
  */
 export declare function parseHighlightMarkup(text: string, options?: HighlightMarkupOptions): React.ReactNode;

package/dist/components/suggestions-primitives/highlightMarkup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"highlightMarkup.d.ts","sourceRoot":"","sources":["../../../src/components/suggestions-primitives/highlightMarkup.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,MAAM,WAAW,sBAAsB;IACrC,yCAAyC;IACzC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2CAA2C;IAC3C,SAAS,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;CACjC;AASD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,sBAA2B,GACnC,KAAK,CAAC,SAAS,CAyBjB"}
+{"version":3,"file":"highlightMarkup.d.ts","sourceRoot":"","sources":["../../../src/components/suggestions-primitives/highlightMarkup.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,8BAA8B;AAC9B,MAAM,MAAM,cAAc,GAAG,YAAY,GAAG,WAAW,GAAG,MAAM,GAAG,YAAY,CAAC;AAEhF,MAAM,WAAW,sBAAsB;IACrC,4CAA4C;IAC5C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAChC,yDAAyD;IACzD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,0CAA0C;IAC1C,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,2CAA2C;IAC3C,mBAAmB,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACtC,qDAAqD;IACrD,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,GAAG,CAAC,iBAAiB,CAAC;CAC5C;AA4CD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,sBAA2B,GACnC,KAAK,CAAC,SAAS,CAkCjB"}

package/dist/components/suggestions-primitives/highlightMarkup.js

@@ -1,6 +1,6 @@
 /**
  * Parses suggestion text containing <mark>...</mark> and returns React nodes
- * with the marked segments rendered as <mark> elements. Safe: inner content
+ * with the marked segments rendered as styled elements. Safe: inner content
  * is rendered as text, not HTML.
  */
 import React from 'react';
@@ -10,9 +10,40 @@ const defaultMarkStyle = {
     borderRadius: '2px',
     padding: '0 2px',
 };
+/** Compute styles based on highlight options */
+function computeHighlightStyles(options) {
+    const style = options.highlightStyle || 'background';
+    const base = {};
+    switch (style) {
+        case 'background':
+            base.backgroundColor = options.highlightColor || 'var(--seekora-highlight-bg, rgba(251, 191, 36, 0.4))';
+            base.borderRadius = '2px';
+            base.padding = '0 2px';
+            break;
+        case 'underline':
+            base.textDecoration = 'underline';
+            base.textDecorationColor = options.highlightColor || 'var(--seekora-highlight-bg, rgba(251, 191, 36, 0.8))';
+            base.textUnderlineOffset = '2px';
+            break;
+        case 'bold':
+            // Only bold, no background
+            break;
+        case 'color-only':
+            // Only color, no background
+            break;
+    }
+    if (options.highlightTextColor) {
+        base.color = options.highlightTextColor;
+    }
+    else {
+        base.color = 'var(--seekora-highlight-color, inherit)';
+    }
+    base.fontWeight = options.highlightFontWeight || 'var(--seekora-highlight-weight, 500)';
+    return base;
+}
 /**
  * Converts a string like "lined <mark>blue</mark>" into React nodes with
- * the marked part rendered as a <mark> element. When no <mark> tags are
+ * the marked part rendered as a styled element. When no <mark> tags are
  * present, returns the string as-is.
  */
 export function parseHighlightMarkup(text, options = {}) {
@@ -21,11 +52,18 @@ export function parseHighlightMarkup(text, options = {}) {
     const parts = text.split(/(<mark>[\s\S]*?<\/mark>)/g);
     if (parts.length <= 1)
         return text;
-    const { markClassName, markStyle } = options;
+    const { markClassName, markStyle, highlightTag } = options;
+    const Tag = (highlightTag || 'mark');
+    // Compute styles: if no custom options provided, use legacy defaults
+    const hasCustomOptions = options.highlightColor || options.highlightTextColor
+        || options.highlightFontWeight || options.highlightStyle;
+    const computedStyle = hasCustomOptions
+        ? computeHighlightStyles(options)
+        : defaultMarkStyle;
     return (React.createElement(React.Fragment, null, parts.map((part, i) => {
         const m = part.match(/^<mark>([\s\S]*)<\/mark>$/);
         if (m) {
-            return (React.createElement("mark", { key: i, className: markClassName, style: { ...defaultMarkStyle, ...markStyle } }, m[1]));
+            return (React.createElement(Tag, { key: i, className: markClassName, style: { ...computedStyle, ...markStyle } }, m[1]));
         }
         return part;
     })));

package/dist/docsearch/components/Results.d.ts

@@ -14,10 +14,12 @@ interface ResultsProps {
     scrollSelectionIntoViewRef?: React.MutableRefObject<boolean>;
     query: string;
     isLoading: boolean;
+    /** Show loading state when fetching and no previous hits (default false: show previous results until new render) */
+    showLoadingState?: boolean;
     error: string | null;
     translations?: DocSearchTranslations;
     sources?: SearchSource[];
 }
-export declare function Results({ hits, groupedHits, selectedIndex, onSelect, onHover, scrollSelectionIntoViewRef, query, isLoading, error, translations, sources: _sources, }: ResultsProps): React.JSX.Element;
+export declare function Results({ hits, groupedHits, selectedIndex, onSelect, onHover, scrollSelectionIntoViewRef, query, isLoading, showLoadingState, error, translations, sources: _sources, }: ResultsProps): React.JSX.Element;
 export {};
 //# sourceMappingURL=Results.d.ts.map

package/dist/docsearch/components/Results.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Results.d.ts","sourceRoot":"","sources":["../../../src/docsearch/components/Results.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA4B,MAAM,OAAO,CAAC;AAEjD,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAEvG,UAAU,WAAW;IACnB,MAAM,EAAE,YAAY,CAAC;IACrB,KAAK,EAAE,mBAAmB,EAAE,CAAC;CAC9B;AAED,UAAU,YAAY;IACpB,IAAI,EAAE,CAAC,YAAY,GAAG,mBAAmB,CAAC,EAAE,CAAC;IAC7C,WAAW,CAAC,EAAE,WAAW,EAAE,CAAC;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,CAAC,GAAG,EAAE,YAAY,GAAG,mBAAmB,KAAK,IAAI,CAAC;IAC5D,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,4GAA4G;IAC5G,0BAA0B,CAAC,EAAE,KAAK,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,YAAY,CAAC,EAAE,qBAAqB,CAAC;IACrC,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;CAC1B;AAuGD,wBAAgB,OAAO,CAAC,EACtB,IAAI,EACJ,WAAW,EACX,aAAa,EACb,QAAQ,EACR,OAAO,EACP,0BAA0B,EAC1B,KAAK,EACL,SAAS,EACT,KAAK,EACL,YAAiB,EACjB,OAAO,EAAE,QAAa,GACvB,EAAE,YAAY,qBAsGd"}
+{"version":3,"file":"Results.d.ts","sourceRoot":"","sources":["../../../src/docsearch/components/Results.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA4B,MAAM,OAAO,CAAC;AAEjD,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAEvG,UAAU,WAAW;IACnB,MAAM,EAAE,YAAY,CAAC;IACrB,KAAK,EAAE,mBAAmB,EAAE,CAAC;CAC9B;AAED,UAAU,YAAY;IACpB,IAAI,EAAE,CAAC,YAAY,GAAG,mBAAmB,CAAC,EAAE,CAAC;IAC7C,WAAW,CAAC,EAAE,WAAW,EAAE,CAAC;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,CAAC,GAAG,EAAE,YAAY,GAAG,mBAAmB,KAAK,IAAI,CAAC;IAC5D,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,4GAA4G;IAC5G,0BAA0B,CAAC,EAAE,KAAK,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;IACnB,oHAAoH;IACpH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,YAAY,CAAC,EAAE,qBAAqB,CAAC;IACrC,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;CAC1B;AAuGD,wBAAgB,OAAO,CAAC,EACtB,IAAI,EACJ,WAAW,EACX,aAAa,EACb,QAAQ,EACR,OAAO,EACP,0BAA0B,EAC1B,KAAK,EACL,SAAS,EACT,gBAAwB,EACxB,KAAK,EACL,YAAiB,EACjB,OAAO,EAAE,QAAa,GACvB,EAAE,YAAY,qBA0Gd"}

package/dist/docsearch/components/Results.js

@@ -79,7 +79,7 @@ function getHitKey(hit, index) {
         return hit.objectID;
     return `suggestion-${hit.url}-${index}`;
 }
-export function Results({ hits, groupedHits, selectedIndex, onSelect, onHover, scrollSelectionIntoViewRef, query, isLoading, error, translations = {}, sources: _sources = [], }) {
+export function Results({ hits, groupedHits, selectedIndex, onSelect, onHover, scrollSelectionIntoViewRef, query, isLoading, showLoadingState = false, error, translations = {}, sources: _sources = [], }) {
     void _sources;
     const listRef = useRef(null);
     useEffect(() => {
@@ -114,7 +114,7 @@ export function Results({ hits, groupedHits, selectedIndex, onSelect, onHover, s
         return (React.createElement("div", { className: "seekora-docsearch-empty" },
             React.createElement("p", { className: "seekora-docsearch-empty-text" }, translations.searchPlaceholder || 'Type to start searching...')));
     }
-    if (isLoading && hits.length === 0) {
+    if (isLoading && hits.length === 0 && showLoadingState) {
         return (React.createElement("div", { className: "seekora-docsearch-loading" },
             React.createElement("div", { className: "seekora-docsearch-loading-spinner" },
                 React.createElement("svg", { width: "24", height: "24", viewBox: "0 0 24 24", "aria-hidden": "true" },
@@ -122,6 +122,10 @@ export function Results({ hits, groupedHits, selectedIndex, onSelect, onHover, s
                         React.createElement("animateTransform", { attributeName: "transform", type: "rotate", from: "0 12 12", to: "360 12 12", dur: "0.8s", repeatCount: "indefinite" })))),
             React.createElement("p", { className: "seekora-docsearch-loading-text" }, translations.loadingText || 'Searching...')));
     }
+    if (isLoading && hits.length === 0) {
+        return React.createElement("div", { className: "seekora-docsearch-empty" });
+    }
+    // When loading with previous hits, fall through and show them (no loading screen)
     if (error) {
         return (React.createElement("div", { className: "seekora-docsearch-error" },
             React.createElement("p", { className: "seekora-docsearch-error-text" }, translations.errorText || error)));

package/dist/hooks/useClickTracking.d.ts

@@ -0,0 +1,36 @@
+/**
+ * useClickTracking Hook
+ *
+ * Wraps result link clicks with analytics fire-before-navigate.
+ * - For target="_blank" links: fires analytics normally (page stays)
+ * - For same-page navigation: uses sendBeacon + small delay before navigation
+ * - Tracks click_target: 'new_tab' | 'same_page' | 'in_page'
+ * - Includes destination_url and source_url in click event payload
+ */
+export type ClickTarget = 'new_tab' | 'same_page' | 'in_page';
+export interface ClickTrackingOptions {
+    /** The destination URL the user is navigating to */
+    destinationUrl?: string;
+    /** The clicked item ID */
+    itemId: string;
+    /** Position in search results (1-based) */
+    position: number;
+    /** Click target type */
+    clickTarget?: ClickTarget;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+export interface UseClickTrackingReturn {
+    /**
+     * Track a click event and optionally delay navigation.
+     * Returns a promise that resolves when tracking is complete.
+     */
+    trackClick: (options: ClickTrackingOptions) => Promise<void>;
+    /**
+     * Create an onClick handler that tracks before navigating.
+     * Use this to wrap <a> tag clicks.
+     */
+    createClickHandler: (options: ClickTrackingOptions, onComplete?: () => void) => (e: React.MouseEvent<HTMLAnchorElement>) => void;
+}
+export declare const useClickTracking: () => UseClickTrackingReturn;
+//# sourceMappingURL=useClickTracking.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useClickTracking.d.ts","sourceRoot":"","sources":["../../src/hooks/useClickTracking.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,CAAC;AAE9D,MAAM,WAAW,oBAAoB;IACnC,oDAAoD;IACpD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,wBAAwB;IACxB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,0BAA0B;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,UAAU,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7D;;;OAGG;IACH,kBAAkB,EAAE,CAClB,OAAO,EAAE,oBAAoB,EAC7B,UAAU,CAAC,EAAE,MAAM,IAAI,KACpB,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,CAAC,iBAAiB,CAAC,KAAK,IAAI,CAAC;CACvD;AAED,eAAO,MAAM,gBAAgB,QAAO,sBAwFnC,CAAC"}

package/dist/hooks/useClickTracking.js

@@ -0,0 +1,96 @@
+/**
+ * useClickTracking Hook
+ *
+ * Wraps result link clicks with analytics fire-before-navigate.
+ * - For target="_blank" links: fires analytics normally (page stays)
+ * - For same-page navigation: uses sendBeacon + small delay before navigation
+ * - Tracks click_target: 'new_tab' | 'same_page' | 'in_page'
+ * - Includes destination_url and source_url in click event payload
+ */
+import { useCallback, useRef } from 'react';
+import { useSearchContext } from '../components/SearchProvider';
+import { useSearchState } from './useSearchState';
+import { sendAnalyticsBeacon } from '@seekora-ai/ui-sdk-core';
+export const useClickTracking = () => {
+    const { client, enableAnalytics, stateManager } = useSearchContext();
+    const { results } = useSearchState();
+    const pendingRef = useRef(false);
+    const trackClick = useCallback(async (options) => {
+        if (!enableAnalytics || pendingRef.current)
+            return;
+        pendingRef.current = true;
+        try {
+            const sourceUrl = typeof window !== 'undefined' ? window.location.href : undefined;
+            const searchContext = results?.context;
+            // Include A/B test fields from state manager (beacon payloads bypass client.trackEvent)
+            const abTestId = stateManager.getAbTestId?.();
+            const abVariant = stateManager.getAbVariant?.();
+            const eventPayload = {
+                event_name: 'product_click',
+                clicked_item_id: options.itemId,
+                position: options.position,
+                destination_url: options.destinationUrl || '',
+                source_url: sourceUrl || '',
+                click_target: options.clickTarget || 'in_page',
+                ...(abTestId && { ab_test_id: abTestId }),
+                ...(abVariant && { ab_variant: abVariant }),
+                ...options.metadata,
+            };
+            // For same_page navigation, use sendBeacon for reliability
+            if (options.clickTarget === 'same_page') {
+                if (client.trackClick) {
+                    // Try sendBeacon approach
+                    const baseUrl = client.baseUrl || client.apiUrl || '';
+                    if (baseUrl) {
+                        sendAnalyticsBeacon(`${baseUrl}/api/analytics/event`, {
+                            ...eventPayload,
+                            ...(searchContext || {}),
+                        });
+                    }
+                }
+            }
+            else {
+                // Normal tracking via client SDK
+                if (client.trackClick) {
+                    await client.trackClick(options.itemId, options.position, searchContext);
+                }
+                else if (client.trackEvent) {
+                    await client.trackEvent(eventPayload, searchContext);
+                }
+            }
+        }
+        catch {
+            // Silently fail — analytics should never break navigation
+        }
+        finally {
+            pendingRef.current = false;
+        }
+    }, [client, enableAnalytics, results, stateManager]);
+    const createClickHandler = useCallback((options, onComplete) => {
+        return (e) => {
+            const anchor = e.currentTarget;
+            const href = anchor.href;
+            const target = anchor.target;
+            const isNewTab = target === '_blank' || e.metaKey || e.ctrlKey;
+            const clickTarget = isNewTab ? 'new_tab' : 'same_page';
+            const trackOptions = { ...options, destinationUrl: href, clickTarget };
+            if (isNewTab) {
+                // New tab: page stays, track normally
+                trackClick(trackOptions);
+                onComplete?.();
+            }
+            else {
+                // Same page: prevent default, track with beacon, then navigate
+                e.preventDefault();
+                trackClick(trackOptions).then(() => {
+                    // Small delay to ensure beacon fires
+                    setTimeout(() => {
+                        onComplete?.();
+                        window.location.href = href;
+                    }, 50);
+                });
+            }
+        };
+    }, [trackClick]);
+    return { trackClick, createClickHandler };
+};

package/dist/hooks/useExperiment.d.ts

@@ -0,0 +1,25 @@
+/**
+ * useExperiment Hook
+ *
+ * Fetches experiment variant assignments from the backend and caches them.
+ * Auto-injects ab_test_id and ab_variant into SearchProvider context.
+ *
+ * Usage:
+ *   const { experimentId, variantId, variantConfig, isLoading } = useExperiment('search-ranking-v2');
+ */
+export interface ExperimentAssignment {
+    experiment_id: string;
+    variant_id: string;
+    variant_config?: Record<string, unknown>;
+}
+export interface UseExperimentReturn {
+    experimentId: string | null;
+    variantId: string | null;
+    variantConfig: Record<string, unknown> | null;
+    isLoading: boolean;
+    error: Error | null;
+    /** All active assignments for the current user */
+    allAssignments: ExperimentAssignment[];
+}
+export declare const useExperiment: (experimentId?: string) => UseExperimentReturn;
+//# sourceMappingURL=useExperiment.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useExperiment.d.ts","sourceRoot":"","sources":["../../src/hooks/useExperiment.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,MAAM,WAAW,oBAAoB;IACnC,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC9C,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,kDAAkD;IAClD,cAAc,EAAE,oBAAoB,EAAE,CAAC;CACxC;AAsCD,eAAO,MAAM,aAAa,GAAI,eAAe,MAAM,KAAG,mBAkHrD,CAAC"}

package/dist/hooks/useExperiment.js

@@ -0,0 +1,146 @@
+/**
+ * useExperiment Hook
+ *
+ * Fetches experiment variant assignments from the backend and caches them.
+ * Auto-injects ab_test_id and ab_variant into SearchProvider context.
+ *
+ * Usage:
+ *   const { experimentId, variantId, variantConfig, isLoading } = useExperiment('search-ranking-v2');
+ */
+import { useState, useEffect, useCallback, useRef } from 'react';
+import { useSearchContext } from '../components/SearchProvider';
+const CACHE_PREFIX = 'seekora_experiment_';
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+function getCachedAssignment(userKey, experimentId) {
+    if (typeof localStorage === 'undefined')
+        return null;
+    try {
+        const key = `${CACHE_PREFIX}${userKey}_${experimentId}`;
+        const raw = localStorage.getItem(key);
+        if (!raw)
+            return null;
+        const cached = JSON.parse(raw);
+        if (Date.now() - cached.timestamp > CACHE_TTL_MS) {
+            localStorage.removeItem(key);
+            return null;
+        }
+        return cached.assignment;
+    }
+    catch {
+        return null;
+    }
+}
+function setCachedAssignment(userKey, assignment) {
+    if (typeof localStorage === 'undefined')
+        return;
+    try {
+        const key = `${CACHE_PREFIX}${userKey}_${assignment.experiment_id}`;
+        const cached = { assignment, timestamp: Date.now() };
+        localStorage.setItem(key, JSON.stringify(cached));
+    }
+    catch {
+        // Silently fail — localStorage may be full or unavailable
+    }
+}
+export const useExperiment = (experimentId) => {
+    const { client, stateManager } = useSearchContext();
+    const [allAssignments, setAllAssignments] = useState([]);
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const fetchedRef = useRef(false);
+    const fetchAssignments = useCallback(async () => {
+        if (fetchedRef.current)
+            return;
+        fetchedRef.current = true;
+        setIsLoading(true);
+        try {
+            // Get user key from client config or generate anonymous one
+            const clientAny = client;
+            const baseUrl = clientAny.baseUrl || clientAny.apiUrl || '';
+            const storeId = clientAny.storeId || clientAny.xStoreId || '';
+            if (!baseUrl || !storeId) {
+                setIsLoading(false);
+                return;
+            }
+            // Try to determine user key
+            const userKey = clientAny.userId || clientAny.anonymousId || clientAny.anonId || '';
+            if (!userKey) {
+                setIsLoading(false);
+                return;
+            }
+            // Check cache first for specific experiment
+            if (experimentId) {
+                const cached = getCachedAssignment(userKey, experimentId);
+                if (cached) {
+                    setAllAssignments([cached]);
+                    // Update state manager and SDK client with cached assignment
+                    stateManager.setAbTest(cached.experiment_id, cached.variant_id);
+                    if (typeof client.setAbTest === 'function') {
+                        client.setAbTest(cached.experiment_id, cached.variant_id);
+                    }
+                    setIsLoading(false);
+                    return;
+                }
+            }
+            // Fetch from backend (requires store authentication for orgID resolution)
+            const readSecret = clientAny.readSecret || clientAny.storeSecret || '';
+            const headers = {
+                'x-storeid': storeId,
+                'x-user-id': userKey,
+            };
+            if (readSecret) {
+                headers['x-storesecret'] = readSecret;
+            }
+            const response = await fetch(`${baseUrl}/api/v1/experiments/assignment`, {
+                headers,
+            });
+            if (!response.ok) {
+                throw new Error(`Failed to fetch experiment assignments: ${response.status}`);
+            }
+            const data = await response.json();
+            const assignments = data.assignments || [];
+            // Cache all assignments
+            assignments.forEach(a => setCachedAssignment(userKey, a));
+            setAllAssignments(assignments);
+            // If a specific experiment was requested, set it on the state manager and SDK client
+            const setAbFields = (expId, varId) => {
+                stateManager.setAbTest(expId, varId);
+                if (typeof client.setAbTest === 'function') {
+                    client.setAbTest(expId, varId);
+                }
+            };
+            if (experimentId) {
+                const match = assignments.find(a => a.experiment_id === experimentId);
+                if (match) {
+                    setAbFields(match.experiment_id, match.variant_id);
+                }
+            }
+            else if (assignments.length > 0) {
+                // Use the first assignment by default
+                setAbFields(assignments[0].experiment_id, assignments[0].variant_id);
+            }
+            setError(null);
+        }
+        catch (err) {
+            setError(err instanceof Error ? err : new Error(String(err)));
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [client, stateManager, experimentId]);
+    useEffect(() => {
+        fetchAssignments();
+    }, [fetchAssignments]);
+    // Find the specific experiment assignment
+    const assignment = experimentId
+        ? allAssignments.find(a => a.experiment_id === experimentId)
+        : allAssignments[0] || null;
+    return {
+        experimentId: assignment?.experiment_id || null,
+        variantId: assignment?.variant_id || null,
+        variantConfig: assignment?.variant_config || null,
+        isLoading,
+        error,
+        allAssignments,
+    };
+};

package/dist/hooks/useKeyboardNavigation.d.ts

@@ -0,0 +1,51 @@
+/**
+ * useKeyboardNavigation Hook
+ *
+ * Shared focus management for navigable component lists.
+ * Handles arrow keys, Enter/Space, Escape, Home/End.
+ * Provides visible focus indicators via CSS variables.
+ */
+export interface KeyboardNavigationOptions {
+    /** Total number of items in the list */
+    itemCount: number;
+    /** Orientation: 'vertical' for up/down, 'horizontal' for left/right */
+    orientation?: 'vertical' | 'horizontal';
+    /** Whether navigation wraps around at boundaries */
+    wrap?: boolean;
+    /** Callback when an item is selected (Enter/Space) */
+    onSelect?: (index: number) => void;
+    /** Callback when Escape is pressed */
+    onEscape?: () => void;
+    /** Callback when Delete/Backspace is pressed on focused item */
+    onDelete?: (index: number) => void;
+    /** Whether keyboard navigation is enabled */
+    enabled?: boolean;
+}
+export interface UseKeyboardNavigationReturn {
+    /** Currently focused item index (-1 = none) */
+    activeIndex: number;
+    /** Set active index programmatically */
+    setActiveIndex: (index: number) => void;
+    /** Props to spread onto the container element */
+    containerProps: {
+        tabIndex: number;
+        role: string;
+        'aria-activedescendant': string | undefined;
+        onKeyDown: (e: React.KeyboardEvent) => void;
+        onBlur: () => void;
+    };
+    /** Get props for an individual item */
+    getItemProps: (index: number) => {
+        id: string;
+        role: string;
+        tabIndex: number;
+        'aria-selected': boolean;
+        onMouseEnter: () => void;
+        onFocus: () => void;
+        style: React.CSSProperties;
+    };
+    /** Whether any item is currently focused */
+    hasFocus: boolean;
+}
+export declare const useKeyboardNavigation: (options: KeyboardNavigationOptions) => UseKeyboardNavigationReturn;
+//# sourceMappingURL=useKeyboardNavigation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useKeyboardNavigation.d.ts","sourceRoot":"","sources":["../../src/hooks/useKeyboardNavigation.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,WAAW,yBAAyB;IACxC,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,WAAW,CAAC,EAAE,UAAU,GAAG,YAAY,CAAC;IACxC,oDAAoD;IACpD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,sDAAsD;IACtD,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IACtB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,6CAA6C;IAC7C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,2BAA2B;IAC1C,+CAA+C;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,wCAAwC;IACxC,cAAc,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,iDAAiD;IACjD,cAAc,EAAE;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,uBAAuB,EAAE,MAAM,GAAG,SAAS,CAAC;QAC5C,SAAS,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,KAAK,IAAI,CAAC;QAC5C,MAAM,EAAE,MAAM,IAAI,CAAC;KACpB,CAAC;IACF,uCAAuC;IACvC,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK;QAC/B,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,eAAe,EAAE,OAAO,CAAC;QACzB,YAAY,EAAE,MAAM,IAAI,CAAC;QACzB,OAAO,EAAE,MAAM,IAAI,CAAC;QACpB,KAAK,EAAE,KAAK,CAAC,aAAa,CAAC;KAC5B,CAAC;IACF,4CAA4C;IAC5C,QAAQ,EAAE,OAAO,CAAC;CACnB;AAaD,eAAO,MAAM,qBAAqB,GAAI,SAAS,yBAAyB,KAAG,2BAkH1E,CAAC"}