@seekora-ai/ui-sdk-react 0.2.24 → 0.2.26

package/dist/src/index.d.ts

@@ -485,6 +485,8 @@ interface FacetsProps {
     hideEmptyFacets?: boolean;
     /** Fields that should start collapsed (collapsible variant only). Overrides defaultCollapsed for listed fields. */
     defaultCollapsedFields?: string[];
+    /** Callback fired when facet availability changes. Receives true when facets are available, false when empty. */
+    onFacetsAvailable?: (available: boolean) => void;
 }
 declare const Facets: React__default.FC<FacetsProps>;
 

package/dist/src/index.esm.js

@@ -302,6 +302,8 @@ class SearchStateManager {
         this.listeners = [];
         this.debounceTimer = null;
         this.notifyScheduled = false;
+        this.searchCoalesceTimer = null;
+        this.searchCoalesceResolvers = [];
         this.client = config.client;
         this.autoSearch = config.autoSearch !== false;
         this.debounceMs = config.debounceMs || 300;
@@ -446,13 +448,27 @@ class SearchStateManager {
             this.debouncedSearch();
         }
     }
-    // Manual search trigger
+    // Manual search trigger — coalesces rapid calls within 10ms into a single API request
     async search(additionalOptions) {
         // Clear debounce timer if exists
         if (this.debounceTimer) {
             clearTimeout(this.debounceTimer);
             this.debounceTimer = null;
         }
+        return new Promise((resolve, reject) => {
+            this.searchCoalesceResolvers.push({ resolve, reject });
+            if (this.searchCoalesceTimer) {
+                clearTimeout(this.searchCoalesceTimer);
+            }
+            this.searchCoalesceTimer = setTimeout(() => {
+                this.searchCoalesceTimer = null;
+                const resolvers = [...this.searchCoalesceResolvers];
+                this.searchCoalesceResolvers = [];
+                this._executeSearch(additionalOptions).then((result) => resolvers.forEach(r => r.resolve(result)), (err) => resolvers.forEach(r => r.reject(err)));
+            }, 10);
+        });
+    }
+    async _executeSearch(additionalOptions) {
         this.setState({ loading: true, error: null });
         try {
             const searchOptions = this.buildSearchOptions(additionalOptions);
@@ -2693,11 +2709,8 @@ function getCurrentBreakpoint(width) {
  * Hook to get current breakpoint
  */
 function useBreakpoint() {
-    const [breakpoint, setBreakpoint] = useState(() => {
-        if (typeof window === 'undefined')
-            return 'lg';
-        return getCurrentBreakpoint(window.innerWidth);
-    });
+    // Always start with 'lg' to avoid hydration mismatch between server and client
+    const [breakpoint, setBreakpoint] = useState('lg');
     useEffect(() => {
         const handleResize = () => {
             setBreakpoint(getCurrentBreakpoint(window.innerWidth));
@@ -2712,11 +2725,8 @@ function useBreakpoint() {
  * Hook to check if current viewport matches breakpoint
  */
 function useMediaQuery(query) {
-    const [matches, setMatches] = useState(() => {
-        if (typeof window === 'undefined')
-            return false;
-        return window.matchMedia(query).matches;
-    });
+    // Always start with false to avoid hydration mismatch between server and client
+    const [matches, setMatches] = useState(false);
     useEffect(() => {
         const mediaQuery = window.matchMedia(query);
         const handleChange = () => setMatches(mediaQuery.matches);
@@ -3512,15 +3522,22 @@ const useFilters = (options) => {
     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 () => {
-        setLoading(true);
+        // 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);
             }
         }
@@ -3531,13 +3548,26 @@ const useFilters = (options) => {
             }
         }
     }, [stateManager, options?.facetBy, options?.maxFacetValues, options?.disjunctiveFacets?.join(',')]);
-    // Refetch when query or refinements change
+    // 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) => {
+        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
@@ -3879,7 +3909,7 @@ const CSS_VAR_DEFAULTS = {
 // ---------------------------------------------------------------------------
 // Component
 // ---------------------------------------------------------------------------
-const Facets = ({ results: resultsProp, facets: facetsProp, onFacetChange, renderFacet, renderFacetItem, maxItems = 10, showMore = true, className, style, theme: customTheme, variant = 'checkbox', searchable = false, showCounts = true, colorMap, defaultCollapsed = false, size = 'medium', facetRanges, useFiltersApi = false, disjunctiveFacets, hideEmptyFacets = true, defaultCollapsedFields, }) => {
+const Facets = ({ results: resultsProp, facets: facetsProp, onFacetChange, renderFacet, renderFacetItem, maxItems = 10, showMore = true, className, style, theme: customTheme, variant = 'checkbox', searchable = false, showCounts = true, colorMap, defaultCollapsed = false, size = 'medium', facetRanges, useFiltersApi = false, disjunctiveFacets, hideEmptyFacets = true, defaultCollapsedFields, onFacetsAvailable, }) => {
     const { theme } = useSearchContext();
     const { results: stateResults, refinements, addRefinement, removeRefinement } = useSearchState();
     const facetsTheme = customTheme || {};
@@ -3957,9 +3987,22 @@ const Facets = ({ results: resultsProp, facets: facetsProp, onFacetChange, rende
         return extracted;
     };
     const rawFacetList = extractFacets();
+    const hasStats = (stats) => stats != null && (stats.min != null || stats.max != null);
     const facets = hideEmptyFacets
-        ? rawFacetList.filter(f => f.items.length > 0 || f.stats != null)
+        ? rawFacetList.filter(f => f.items.length > 0 || hasStats(f.stats))
         : rawFacetList;
+    // Notify parent about facet availability
+    const facetCount = facets.length;
+    const prevFacetAvailableRef = useRef(null);
+    useEffect(() => {
+        if (!onFacetsAvailable)
+            return;
+        const available = facetCount > 0;
+        if (prevFacetAvailableRef.current !== available) {
+            prevFacetAvailableRef.current = available;
+            onFacetsAvailable(available);
+        }
+    }, [facetCount, onFacetsAvailable]);
     // -------------------------------------------------------------------
     // Handlers
     // -------------------------------------------------------------------
@@ -5199,9 +5242,6 @@ const CurrentRefinements = ({ refinements: refinementsProp, onRefinementClear, o
                     opacity: 0.6,
                 }, "aria-label": `Clear ${refinement.label || refinement.field}: ${refinement.value}`, onMouseEnter: e => (e.currentTarget.style.opacity = '1'), onMouseLeave: e => (e.currentTarget.style.opacity = '0.6') }, renderCloseIcon ? renderCloseIcon() : defaultCloseIcon())));
     };
-    if (refinements.length === 0) {
-        return null;
-    }
     // Group refinements by field for grouped layout
     const groupedRefinements = layout === 'grouped'
         ? refinements.reduce((acc, r) => {
@@ -5213,13 +5253,17 @@ const CurrentRefinements = ({ refinements: refinementsProp, onRefinementClear, o
         : null;
     const containerStyles = {
         ...style,
+        // When a custom list theme is provided, make the container transparent to layout
+        // so the list div becomes the direct layout child (enables overflow scroll from parent)
+        ...(refinementsTheme.list && !style?.display ? { display: 'contents' } : {}),
     };
     const listStyles = {
         display: 'flex',
-        flexWrap: layout === 'vertical' ? 'nowrap' : 'wrap',
         flexDirection: layout === 'vertical' ? 'column' : 'row',
         alignItems: layout === 'vertical' ? 'flex-start' : 'center',
-        marginBottom: showClearAll ? theme.spacing.medium : 0,
+        marginBottom: showClearAll && refinements.length > 0 ? theme.spacing.medium : 0,
+        // Only apply flex-wrap if no custom list theme is provided (let theme classes control wrapping)
+        ...(!refinementsTheme.list ? { flexWrap: layout === 'vertical' ? 'nowrap' : 'wrap' } : {}),
     };
     return (React.createElement("div", { className: clsx(refinementsTheme.container, className), style: containerStyles },
         React.createElement("style", null, `
@@ -5228,34 +5272,35 @@ const CurrentRefinements = ({ refinements: refinementsProp, onRefinementClear, o
           to { opacity: 1; transform: scale(1); }
         }
       `),
-        layout === 'grouped' && groupedRefinements ? (Object.entries(groupedRefinements).map(([field, items]) => (React.createElement("div", { key: field, className: refinementsTheme.group, style: { marginBottom: theme.spacing.medium } },
-            React.createElement("div", { className: refinementsTheme.groupLabel, style: {
-                    fontSize: theme.typography.fontSize.small,
-                    fontWeight: 600,
-                    color: theme.colors.text,
-                    marginBottom: theme.spacing.small,
-                    textTransform: 'capitalize',
-                } }, items[0]?.label || field),
-            React.createElement("div", { role: "list", style: listStyles }, items.map((refinement, index) => {
+        refinements.length > 0 && (React.createElement(React.Fragment, null,
+            layout === 'grouped' && groupedRefinements ? (Object.entries(groupedRefinements).map(([field, items]) => (React.createElement("div", { key: field, className: refinementsTheme.group, style: { marginBottom: theme.spacing.medium } },
+                React.createElement("div", { className: refinementsTheme.groupLabel, style: {
+                        fontSize: theme.typography.fontSize.small,
+                        fontWeight: 600,
+                        color: theme.colors.text,
+                        marginBottom: theme.spacing.small,
+                        textTransform: 'capitalize',
+                    } }, items[0]?.label || field),
+                React.createElement("div", { role: "list", style: listStyles }, items.map((refinement, index) => {
+                    return renderRefinement
+                        ? renderRefinement(refinement, index)
+                        : defaultRenderRefinement(refinement, index);
+                })))))) : (React.createElement("div", { role: "list", className: refinementsTheme.list, style: listStyles }, refinements.map((refinement, index) => {
                 return renderRefinement
                     ? renderRefinement(refinement, index)
                     : defaultRenderRefinement(refinement, index);
-            })))))) : (React.createElement("div", { role: "list", className: refinementsTheme.list, style: listStyles }, refinements.map((refinement, index) => {
-            return renderRefinement
-                ? renderRefinement(refinement, index)
-                : defaultRenderRefinement(refinement, index);
-        }))),
-        showClearAll && refinements.length > 1 && (React.createElement("button", { type: "button", onClick: handleClearAll, className: refinementsTheme.clearAllButton, style: {
-                padding: `${theme.spacing.small} ${theme.spacing.medium}`,
-                border: `1px solid ${theme.colors.border}`,
-                borderRadius: typeof theme.borderRadius === 'string' ? theme.borderRadius : theme.borderRadius.medium,
-                backgroundColor: theme.colors.background,
-                color: theme.colors.text,
-                cursor: 'pointer',
-                fontSize: theme.typography.fontSize.small,
-                textDecoration: 'underline',
-                transition: `background-color ${TRANSITIONS$7.fast}`,
-            } }, "Clear all filters"))));
+            }))),
+            showClearAll && refinements.length > 1 && (React.createElement("button", { type: "button", onClick: handleClearAll, className: refinementsTheme.clearAllButton, style: {
+                    padding: `${theme.spacing.small} ${theme.spacing.medium}`,
+                    border: `1px solid ${theme.colors.border}`,
+                    borderRadius: typeof theme.borderRadius === 'string' ? theme.borderRadius : theme.borderRadius.medium,
+                    backgroundColor: theme.colors.background,
+                    color: theme.colors.text,
+                    cursor: 'pointer',
+                    fontSize: theme.typography.fontSize.small,
+                    textDecoration: 'underline',
+                    transition: `background-color ${TRANSITIONS$7.fast}`,
+                } }, "Clear all filters"))))));
 };
 
 /**
@@ -5323,16 +5368,17 @@ const ClearRefinements = ({ clearsQuery = false, resetLabel = 'Clear all filters
                 padding: `${theme.spacing.small} ${theme.spacing.medium}`,
                 fontSize: theme.typography.fontSize.medium,
                 fontWeight: theme.typography.fontWeight?.medium || 500,
-                backgroundColor: canClear ? theme.colors.primary : theme.colors.hover,
-                color: canClear ? '#ffffff' : theme.colors.textSecondary,
+                backgroundColor: theme.colors.primary,
+                color: '#ffffff',
                 border: 'none',
                 borderRadius: typeof theme.borderRadius === 'string'
                     ? theme.borderRadius
                     : theme.borderRadius.medium,
-                cursor: canClear ? 'pointer' : 'not-allowed',
-                opacity: canClear ? 1 : 0.6,
-                transition: theme.transitions?.fast || '150ms ease-in-out',
-            }, "aria-label": canClear ? resetLabel : disabledLabel }, canClear ? resetLabel : disabledLabel)));
+                cursor: canClear ? 'pointer' : 'default',
+                opacity: canClear ? 1 : 0,
+                pointerEvents: canClear ? 'auto' : 'none',
+                transition: 'none',
+            }, "aria-label": resetLabel }, resetLabel)));
 };
 
 /**
@@ -5370,7 +5416,7 @@ const SearchLayout = ({ sidebar, children, header, footer, sidebarWidth = '300px
                 padding: responsivePadding,
                 backgroundColor: theme.colors.background,
                 color: theme.colors.text,
-                overflow: isMobile ? 'visible' : 'hidden',
+                overflow: 'visible',
             } },
             sidebar && (!isMobile || showSidebarOnMobile) && (React.createElement("aside", { className: layoutTheme.sidebar, style: {
                     width: isMobile ? '100%' : sidebarWidth,