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

package/dist/hooks/useAnalytics.d.ts

@@ -0,0 +1,24 @@
+/**
+ * useAnalytics Hook
+ *
+ * Hook for tracking analytics events with the Seekora SDK.
+ * Supports Analytics V3 payload fields (event_ts, anonymous_id, orgcode, xstoreid);
+ * the SDK sends both legacy and v3 fields for backend compatibility.
+ */
+import type { SeekoraClient, SearchContext, ExtendedEventPayload, DataTypesEventPayload } from '@seekora-ai/search-sdk';
+export interface UseAnalyticsOptions {
+    client: SeekoraClient;
+    enabled?: boolean;
+}
+/** Payload for trackEvent/trackBatch: supports legacy and Analytics V3 field names */
+export type AnalyticsEventPayload = Partial<DataTypesEventPayload> & Partial<ExtendedEventPayload>;
+export interface UseAnalyticsReturn {
+    trackEvent: (eventType: string, payload: AnalyticsEventPayload, context?: SearchContext | Partial<SearchContext>) => Promise<void>;
+    trackClick: (resultId: string, result: any, context?: SearchContext | Partial<SearchContext>, position?: number) => Promise<void>;
+    trackConversion: (resultId: string, result: any, value?: number, currency?: string, context?: SearchContext | Partial<SearchContext>) => Promise<void>;
+    trackBatch: (events: (AnalyticsEventPayload & {
+        event_name?: string;
+    })[], context?: SearchContext) => Promise<void>;
+}
+export declare const useAnalytics: ({ client, enabled, }: UseAnalyticsOptions) => UseAnalyticsReturn;
+//# sourceMappingURL=useAnalytics.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useAnalytics.d.ts","sourceRoot":"","sources":["../../src/hooks/useAnalytics.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAGxH,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,aAAa,CAAC;IACtB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,sFAAsF;AACtF,MAAM,MAAM,qBAAqB,GAAG,OAAO,CAAC,qBAAqB,CAAC,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;AAEnG,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,qBAAqB,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACnI,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,EAAE,QAAQ,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClI,eAAe,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvJ,UAAU,EAAE,CAAC,MAAM,EAAE,CAAC,qBAAqB,GAAG;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,EAAE,EAAE,OAAO,CAAC,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACrH;AAED,eAAO,MAAM,YAAY,GAAI,sBAG1B,mBAAmB,KAAG,kBA6ExB,CAAC"}

package/dist/hooks/useAnalytics.js

@@ -0,0 +1,67 @@
+/**
+ * useAnalytics Hook
+ *
+ * Hook for tracking analytics events with the Seekora SDK.
+ * Supports Analytics V3 payload fields (event_ts, anonymous_id, orgcode, xstoreid);
+ * the SDK sends both legacy and v3 fields for backend compatibility.
+ */
+import { useCallback } from 'react';
+import { log } from '@seekora-ai/ui-sdk-core';
+export const useAnalytics = ({ client, enabled = true, }) => {
+    const trackEvent = useCallback(async (eventType, payload, context) => {
+        if (!enabled)
+            return;
+        try {
+            const eventPayload = {
+                event_name: eventType,
+                ...payload,
+            };
+            await client.trackEvent?.(eventPayload, context);
+        }
+        catch (err) {
+            log.error('Failed to track event:', err);
+        }
+    }, [client, enabled]);
+    const trackClick = useCallback(async (resultId, result, context, position) => {
+        if (!enabled)
+            return;
+        const pos = position ?? 0;
+        if (client.trackClick) {
+            await client.trackClick(resultId, pos, context);
+        }
+        else {
+            await trackEvent('product_click', {
+                clicked_item_id: resultId,
+                metadata: { result, ...(position !== undefined && { position: pos }) },
+            }, context);
+        }
+    }, [client, trackEvent, enabled]);
+    const trackConversion = useCallback(async (resultId, result, value, currency, context) => {
+        if (!enabled)
+            return;
+        await trackEvent('conversion', {
+            clicked_item_id: resultId,
+            value: value,
+            currency: currency,
+            metadata: {
+                result: result,
+            },
+        }, context);
+    }, [trackEvent, enabled]);
+    const trackBatch = useCallback(async (events, context) => {
+        if (!enabled || events.length === 0)
+            return;
+        try {
+            await client.trackEvents?.(events, context);
+        }
+        catch (err) {
+            log.error('Failed to track batch events:', err);
+        }
+    }, [client, enabled]);
+    return {
+        trackEvent,
+        trackClick,
+        trackConversion,
+        trackBatch,
+    };
+};

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,sBAkFnC,CAAC"}

package/dist/hooks/useClickTracking.js

@@ -0,0 +1,89 @@
+/**
+ * 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';
+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,
+            };
+            if (options.clickTarget === 'same_page') {
+                // For same_page navigation, track via SDK then flush to ensure delivery before navigation
+                if (client.trackEvent) {
+                    await client.trackEvent(eventPayload, searchContext);
+                    await client.flushEventQueue();
+                }
+            }
+            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,mBAuFrD,CAAC"}

package/dist/hooks/useExperiment.js

@@ -0,0 +1,123 @@
+/**
+ * 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 {
+            // Try to determine user key for caching
+            const clientAny = client;
+            const userKey = clientAny.userId || clientAny.anonymousId || clientAny.anonId || '';
+            // Check cache first for specific experiment
+            if (experimentId && userKey) {
+                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 clientAny.setAbTest === 'function') {
+                        clientAny.setAbTest(cached.experiment_id, cached.variant_id);
+                    }
+                    setIsLoading(false);
+                    return;
+                }
+            }
+            // Fetch from backend via SDK client (handles auth, baseUrl, headers internally)
+            if (typeof clientAny.getExperimentAssignment !== 'function') {
+                setIsLoading(false);
+                return;
+            }
+            const data = await client.getExperimentAssignment();
+            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);
+                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/useFilters.d.ts

@@ -0,0 +1,27 @@
+/**
+ * useFilters Hook
+ *
+ * React hook for fetching filter values, searching facet values,
+ * and retrieving filter schema via the dedicated Filters API.
+ */
+import type { FilterOptions, FilterField, FiltersSchemaResponse, FacetValuesSearchResponse } from '@seekora-ai/search-sdk';
+export interface UseFiltersOptions extends FilterOptions {
+    /** Whether to automatically refetch filters when query or refinements change (default: true) */
+    autoFetch?: boolean;
+}
+export interface UseFiltersReturn {
+    /** Filter fields with values and counts */
+    filters: FilterField[];
+    /** Filter schema metadata (fetched once on mount) */
+    schema: FiltersSchemaResponse | null;
+    /** Whether filters are currently loading */
+    loading: boolean;
+    /** Error from the last fetch, if any */
+    error: Error | null;
+    /** Search within a facet's values (for typeahead/autocomplete) */
+    searchFacetValues: (facetName: string, query: string) => Promise<FacetValuesSearchResponse>;
+    /** Manually refetch filters */
+    refetch: () => Promise<void>;
+}
+export declare const useFilters: (options?: UseFiltersOptions) => UseFiltersReturn;
+//# sourceMappingURL=useFilters.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useFilters.d.ts","sourceRoot":"","sources":["../../src/hooks/useFilters.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EACV,aAAa,EACb,WAAW,EACX,qBAAqB,EACrB,yBAAyB,EAC1B,MAAM,wBAAwB,CAAC;AAIhC,MAAM,WAAW,iBAAkB,SAAQ,aAAa;IACtD,gGAAgG;IAChG,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,2CAA2C;IAC3C,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,qDAAqD;IACrD,MAAM,EAAE,qBAAqB,GAAG,IAAI,CAAC;IACrC,4CAA4C;IAC5C,OAAO,EAAE,OAAO,CAAC;IACjB,wCAAwC;IACxC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,kEAAkE;IAClE,iBAAiB,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,yBAAyB,CAAC,CAAC;IAC5F,+BAA+B;IAC/B,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED,eAAO,MAAM,UAAU,GAAI,UAAU,iBAAiB,KAAG,gBA2FxD,CAAC"}

package/dist/hooks/useFilters.js

@@ -0,0 +1,86 @@
+/**
+ * useFilters Hook
+ *
+ * React hook for fetching filter values, searching facet values,
+ * and retrieving filter schema via the dedicated Filters API.
+ */
+import { useState, useEffect, useCallback, useRef } from 'react';
+import { useSearchContext } from '../components/SearchProvider';
+export const useFilters = (options) => {
+    const { stateManager } = useSearchContext();
+    const [filters, setFilters] = useState([]);
+    const [schema, setSchema] = useState(null);
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const mountedRef = useRef(true);
+    const autoFetch = options?.autoFetch !== false;
+    // Track whether we've completed the first fetch (to avoid skeleton flash on refetches)
+    const hasDataRef = useRef(false);
+    // Extract non-autoFetch options to pass to fetchFilters
+    const fetchFilters = useCallback(async () => {
+        // Only show loading spinner on the very first fetch; subsequent refetches
+        // keep previous data visible to avoid skeleton/flash on facet changes.
+        if (!hasDataRef.current) {
+            setLoading(true);
+        }
+        setError(null);
+        try {
+            const { autoFetch: _, ...filterOptions } = options || {};
+            const response = await stateManager.fetchFilters(filterOptions);
+            if (mountedRef.current) {
+                setFilters(response?.filters || []);
+                hasDataRef.current = true;
+                setLoading(false);
+            }
+        }
+        catch (err) {
+            if (mountedRef.current) {
+                setError(err instanceof Error ? err : new Error(String(err)));
+                setLoading(false);
+            }
+        }
+    }, [stateManager, options?.facetBy, options?.maxFacetValues, options?.disjunctiveFacets?.join(',')]);
+    // Track query to only refetch filters when query actually changes.
+    // Sentinel ensures the first subscribe callback always triggers a fetch.
+    const prevKeyRef = useRef(null);
+    // Refetch when query or refinements change (not on every state update)
+    useEffect(() => {
+        if (!autoFetch)
+            return;
+        const unsubscribe = stateManager.subscribe((state) => {
+            // Only track query changes — refinements are NOT passed to the Filters API
+            // (facets are generated from search query only, not narrowed by active filters).
+            // This prevents redundant filters refetches on every facet toggle.
+            const key = state.query;
+            if (key === prevKeyRef.current)
+                return;
+            prevKeyRef.current = key;
+            fetchFilters();
+        });
+        // subscribe() immediately invokes the listener with current state,
+        // which handles the initial fetch (prevKeyRef starts as '' so key
+        // will differ). No explicit fetchFilters() call needed here.
+        return unsubscribe;
+    }, [stateManager, autoFetch, fetchFilters]);
+    // Fetch schema once on mount
+    useEffect(() => {
+        stateManager.getFiltersSchema().then((response) => {
+            if (mountedRef.current) {
+                setSchema(response);
+            }
+        }).catch(() => {
+            // Schema fetch failure is non-critical
+        });
+    }, [stateManager]);
+    // Cleanup
+    useEffect(() => {
+        return () => {
+            mountedRef.current = false;
+        };
+    }, []);
+    const searchFacetValues = useCallback((facetName, query) => stateManager.searchFacetValues(facetName, query), [stateManager]);
+    const refetch = useCallback(async () => {
+        await fetchFilters();
+    }, [fetchFilters]);
+    return { filters, schema, loading, error, searchFacetValues, refetch };
+};

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

package/dist/hooks/useKeyboardNavigation.js

@@ -0,0 +1,113 @@
+/**
+ * useKeyboardNavigation Hook
+ *
+ * Shared focus management for navigable component lists.
+ * Handles arrow keys, Enter/Space, Escape, Home/End.
+ * Provides visible focus indicators via CSS variables.
+ */
+import { useState, useCallback, useRef, useEffect } from 'react';
+const FOCUS_RING_STYLE = {
+    outline: '2px solid var(--seekora-focus-color, #2563eb)',
+    outlineOffset: '2px',
+};
+const NO_FOCUS_STYLE = {
+    outline: 'none',
+};
+let idCounter = 0;
+export const useKeyboardNavigation = (options) => {
+    const { itemCount, orientation = 'vertical', wrap = false, onSelect, onEscape, onDelete, enabled = true, } = options;
+    const [activeIndex, setActiveIndex] = useState(-1);
+    const idPrefixRef = useRef(`seekora-nav-${++idCounter}`);
+    // Reset active index when item count changes
+    useEffect(() => {
+        if (activeIndex >= itemCount) {
+            setActiveIndex(itemCount > 0 ? itemCount - 1 : -1);
+        }
+    }, [itemCount, activeIndex]);
+    const moveNext = useCallback(() => {
+        setActiveIndex(prev => {
+            if (prev >= itemCount - 1) {
+                return wrap ? 0 : prev;
+            }
+            return prev + 1;
+        });
+    }, [itemCount, wrap]);
+    const movePrev = useCallback(() => {
+        setActiveIndex(prev => {
+            if (prev <= 0) {
+                return wrap ? itemCount - 1 : (prev === -1 ? 0 : prev);
+            }
+            return prev - 1;
+        });
+    }, [itemCount, wrap]);
+    const handleKeyDown = useCallback((e) => {
+        if (!enabled || itemCount === 0)
+            return;
+        const nextKey = orientation === 'vertical' ? 'ArrowDown' : 'ArrowRight';
+        const prevKey = orientation === 'vertical' ? 'ArrowUp' : 'ArrowLeft';
+        switch (e.key) {
+            case nextKey:
+                e.preventDefault();
+                moveNext();
+                break;
+            case prevKey:
+                e.preventDefault();
+                movePrev();
+                break;
+            case 'Enter':
+            case ' ':
+                if (activeIndex >= 0) {
+                    e.preventDefault();
+                    onSelect?.(activeIndex);
+                }
+                break;
+            case 'Escape':
+                e.preventDefault();
+                setActiveIndex(-1);
+                onEscape?.();
+                break;
+            case 'Home':
+                e.preventDefault();
+                setActiveIndex(0);
+                break;
+            case 'End':
+                e.preventDefault();
+                setActiveIndex(itemCount - 1);
+                break;
+            case 'Delete':
+            case 'Backspace':
+                if (activeIndex >= 0) {
+                    e.preventDefault();
+                    onDelete?.(activeIndex);
+                }
+                break;
+        }
+    }, [enabled, itemCount, orientation, activeIndex, moveNext, movePrev, onSelect, onEscape, onDelete]);
+    const handleBlur = useCallback(() => {
+        // Delay reset to allow click events to fire
+        setTimeout(() => setActiveIndex(-1), 150);
+    }, []);
+    const containerProps = {
+        tabIndex: enabled ? 0 : -1,
+        role: orientation === 'vertical' ? 'listbox' : 'list',
+        'aria-activedescendant': activeIndex >= 0 ? `${idPrefixRef.current}-${activeIndex}` : undefined,
+        onKeyDown: handleKeyDown,
+        onBlur: handleBlur,
+    };
+    const getItemProps = useCallback((index) => ({
+        id: `${idPrefixRef.current}-${index}`,
+        role: 'option',
+        tabIndex: -1,
+        'aria-selected': index === activeIndex,
+        onMouseEnter: () => setActiveIndex(index),
+        onFocus: () => setActiveIndex(index),
+        style: index === activeIndex ? FOCUS_RING_STYLE : NO_FOCUS_STYLE,
+    }), [activeIndex]);
+    return {
+        activeIndex,
+        setActiveIndex,
+        containerProps,
+        getItemProps,
+        hasFocus: activeIndex >= 0,
+    };
+};