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

package/dist/components/FacetDropdown.d.ts

@@ -0,0 +1,94 @@
+/**
+ * FacetDropdown Component
+ *
+ * A dropdown component that displays facet values from a specific field
+ * and allows users to filter search results by selecting values.
+ *
+ * Can be used standalone (fetches its own data) or integrated with SearchProvider.
+ *
+ * @cssVariables
+ * Customize the dropdown appearance using CSS variables:
+ *
+ * Button:
+ * - `--facet-dropdown-button-bg`: Button background color
+ * - `--facet-dropdown-text`: Button text color
+ * - `--facet-dropdown-border`: Button and panel border color
+ * - `--facet-dropdown-font-size`: Button font size (default: 0.875rem)
+ * - `--facet-dropdown-font-weight`: Button font weight (default: 500)
+ *
+ * Dropdown Panel:
+ * - `--facet-dropdown-bg`: Panel background color
+ * - `--facet-dropdown-shadow`: Panel box shadow
+ *
+ * Options:
+ * - `--facet-dropdown-option-text`: Option text color
+ * - `--facet-dropdown-option-font-size`: Option font size (default: 0.875rem)
+ * - `--facet-dropdown-option-font-weight-active`: Active option font weight (default: 500)
+ * - `--facet-dropdown-option-active-bg`: Active option background color
+ *
+ * Count Badge:
+ * - `--facet-dropdown-count-text`: Count text color
+ * - `--facet-dropdown-count-font-size`: Count font size (default: 0.75rem)
+ *
+ * Scrollbar:
+ * - `--facet-dropdown-scrollbar-thumb`: Scrollbar thumb color
+ * - `--facet-dropdown-scrollbar-thumb-hover`: Scrollbar thumb hover color
+ *
+ * @example
+ * ```tsx
+ * <FacetDropdown
+ *   field="category"
+ *   placeholder="All Categories"
+ *   applyFilter={true}
+ *   showCounts={true}
+ * />
+ * ```
+ */
+import React from 'react';
+import type { SeekoraClient } from '@seekora-ai/search-sdk';
+export interface FacetDropdownOption {
+    value: string;
+    count: number;
+    label?: string;
+}
+export interface FacetDropdownTheme {
+    button?: string;
+    buttonOpen?: string;
+    panel?: string;
+    option?: string;
+    optionActive?: string;
+    optionHover?: string;
+    caretIcon?: string;
+}
+export interface FacetDropdownProps {
+    /** The facet field to display (e.g., "category", "brand", "product_type") */
+    field: string;
+    /** Placeholder text when no value is selected */
+    placeholder?: string;
+    /** Custom className for the button */
+    className?: string;
+    /** Custom theme overrides */
+    theme?: FacetDropdownTheme;
+    /** Called when a value is selected */
+    onChange?: (value: string) => void;
+    /** Current selected value (controlled mode) */
+    value?: string;
+    /** Maximum number of options to show before scrolling */
+    maxOptions?: number;
+    /** Whether to show facet counts */
+    showCounts?: boolean;
+    /** Custom options (if you want to provide static options instead of fetching) */
+    options?: FacetDropdownOption[];
+    /** Standalone mode: provide your own search client */
+    client?: SeekoraClient;
+    /** Apply filter immediately on selection (default: true) */
+    applyFilter?: boolean;
+    /** Navigate to search page on selection (default: false) */
+    navigateOnSelect?: boolean;
+    /** Base URL for navigation (e.g., "/search") */
+    searchPageUrl?: string;
+    /** Use dedicated Filters API instead of search API for fetching facet values */
+    useFiltersApi?: boolean;
+}
+export declare const FacetDropdown: React.FC<FacetDropdownProps>;
+//# sourceMappingURL=FacetDropdown.d.ts.map

package/dist/components/FacetDropdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FacetDropdown.d.ts","sourceRoot":"","sources":["../../src/components/FacetDropdown.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,KAAmD,MAAM,OAAO,CAAC;AAKxE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAe5D,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sCAAsC;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6BAA6B;IAC7B,KAAK,CAAC,EAAE,kBAAkB,CAAC;IAC3B,sCAAsC;IACtC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mCAAmC;IACnC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,iFAAiF;IACjF,OAAO,CAAC,EAAE,mBAAmB,EAAE,CAAC;IAChC,sDAAsD;IACtD,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,4DAA4D;IAC5D,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,gDAAgD;IAChD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gFAAgF;IAChF,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAMD,eAAO,MAAM,aAAa,EAAE,KAAK,CAAC,EAAE,CAAC,kBAAkB,CAmctD,CAAC"}

package/dist/components/FacetDropdown.js

@@ -0,0 +1,396 @@
+/**
+ * FacetDropdown Component
+ *
+ * A dropdown component that displays facet values from a specific field
+ * and allows users to filter search results by selecting values.
+ *
+ * Can be used standalone (fetches its own data) or integrated with SearchProvider.
+ *
+ * @cssVariables
+ * Customize the dropdown appearance using CSS variables:
+ *
+ * Button:
+ * - `--facet-dropdown-button-bg`: Button background color
+ * - `--facet-dropdown-text`: Button text color
+ * - `--facet-dropdown-border`: Button and panel border color
+ * - `--facet-dropdown-font-size`: Button font size (default: 0.875rem)
+ * - `--facet-dropdown-font-weight`: Button font weight (default: 500)
+ *
+ * Dropdown Panel:
+ * - `--facet-dropdown-bg`: Panel background color
+ * - `--facet-dropdown-shadow`: Panel box shadow
+ *
+ * Options:
+ * - `--facet-dropdown-option-text`: Option text color
+ * - `--facet-dropdown-option-font-size`: Option font size (default: 0.875rem)
+ * - `--facet-dropdown-option-font-weight-active`: Active option font weight (default: 500)
+ * - `--facet-dropdown-option-active-bg`: Active option background color
+ *
+ * Count Badge:
+ * - `--facet-dropdown-count-text`: Count text color
+ * - `--facet-dropdown-count-font-size`: Count font size (default: 0.75rem)
+ *
+ * Scrollbar:
+ * - `--facet-dropdown-scrollbar-thumb`: Scrollbar thumb color
+ * - `--facet-dropdown-scrollbar-thumb-hover`: Scrollbar thumb hover color
+ *
+ * @example
+ * ```tsx
+ * <FacetDropdown
+ *   field="category"
+ *   placeholder="All Categories"
+ *   applyFilter={true}
+ *   showCounts={true}
+ * />
+ * ```
+ */
+import React, { useState, useEffect, useRef, useCallback } from 'react';
+import { createPortal } from 'react-dom';
+import { useSearchContext } from './SearchProvider';
+import { useSearchState } from '../hooks/useSearchState';
+import { log } from '@seekora-ai/ui-sdk-core';
+// Z-index scale for consistent layering
+// SearchOverlay uses z-100, so dropdown must be higher
+const Z_INDEX = {
+    dropdown: 150, // Higher than SearchOverlay (100)
+    modal: 200,
+    overlay: 300,
+    tooltip: 50,
+};
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+export const FacetDropdown = ({ field, placeholder = 'All Categories', className, theme: customTheme = {}, onChange, value: controlledValue, maxOptions = 10, showCounts = true, options: providedOptions, client: providedClient, applyFilter = true, navigateOnSelect = false, searchPageUrl = '/search', useFiltersApi = false, }) => {
+    const { client: contextClient, theme, stateManager } = useSearchContext();
+    const { addRefinement, removeRefinement, refinements, search } = useSearchState();
+    const client = providedClient || contextClient;
+    const [open, setOpen] = useState(false);
+    const [facetOptions, setFacetOptions] = useState(providedOptions || []);
+    const [internalValue, setInternalValue] = useState(controlledValue || '');
+    const [dropdownPosition, setDropdownPosition] = useState(null);
+    const dropdownRef = useRef(null);
+    const buttonRef = useRef(null);
+    // Determine the current value (controlled or uncontrolled)
+    const currentValue = controlledValue !== undefined ? controlledValue : internalValue;
+    // ---------------------------------------------------------------------------
+    // Fetch facet values
+    // ---------------------------------------------------------------------------
+    const fetchFacetValues = useCallback(async () => {
+        if (providedOptions || !client)
+            return;
+        try {
+            log.verbose('FacetDropdown: Fetching facet values', { field, useFiltersApi });
+            if (useFiltersApi) {
+                // Use dedicated Filters API via state manager
+                const response = await stateManager.fetchFilters({
+                    facetBy: field,
+                    maxFacetValues: 100,
+                });
+                const targetFilter = (response?.filters || []).find((f) => f.field === field);
+                if (targetFilter && targetFilter.values) {
+                    const options = targetFilter.values.map((v) => ({
+                        value: v.value || '',
+                        count: v.count || 0,
+                        label: v.value || '',
+                    }));
+                    setFacetOptions(options);
+                    log.verbose('FacetDropdown: Facet options loaded via Filters API', { field, count: options.length });
+                }
+                else {
+                    log.verbose('FacetDropdown: No filter data found', { field });
+                    setFacetOptions([]);
+                }
+            }
+            else {
+                // Fallback: use search API with per_page=0
+                const response = await client.search('*', {
+                    facet_by: field,
+                    max_facet_values: 100,
+                    per_page: 0,
+                });
+                log.verbose('FacetDropdown: Search response', { response });
+                const facetsData = response?.data?.facets || response?.facets;
+                const facets = Array.isArray(facetsData) ? facetsData : [];
+                const targetFacet = facets.find((f) => f.field_name === field || f.field === field);
+                if (targetFacet && targetFacet.counts) {
+                    const options = targetFacet.counts.map((count) => ({
+                        value: count.value,
+                        count: count.count,
+                        label: count.value,
+                    }));
+                    setFacetOptions(options);
+                    log.verbose('FacetDropdown: Facet options loaded', { field, count: options.length });
+                }
+                else {
+                    log.verbose('FacetDropdown: No facet data found', { field, facets });
+                    setFacetOptions([]);
+                }
+            }
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            log.error('FacetDropdown: Error fetching facet values', {
+                field,
+                error: err.message,
+            });
+            setFacetOptions([]);
+        }
+    }, [field, client, providedOptions, useFiltersApi]);
+    useEffect(() => {
+        if (!providedOptions && client) {
+            fetchFacetValues();
+        }
+    }, [fetchFacetValues, providedOptions, client]);
+    // ---------------------------------------------------------------------------
+    // Calculate dropdown position when opened
+    // ---------------------------------------------------------------------------
+    useEffect(() => {
+        if (!open || !buttonRef.current)
+            return;
+        const updatePosition = () => {
+            if (!buttonRef.current)
+                return;
+            const rect = buttonRef.current.getBoundingClientRect();
+            setDropdownPosition({
+                top: rect.bottom + window.scrollY + 4,
+                left: rect.left + window.scrollX,
+                width: rect.width,
+            });
+        };
+        updatePosition();
+        window.addEventListener('scroll', updatePosition, true);
+        window.addEventListener('resize', updatePosition);
+        return () => {
+            window.removeEventListener('scroll', updatePosition, true);
+            window.removeEventListener('resize', updatePosition);
+        };
+    }, [open]);
+    // ---------------------------------------------------------------------------
+    // Click outside handler
+    // ---------------------------------------------------------------------------
+    useEffect(() => {
+        if (!open)
+            return;
+        const handleClickOutside = (e) => {
+            if (dropdownRef.current &&
+                !dropdownRef.current.contains(e.target) &&
+                buttonRef.current &&
+                !buttonRef.current.contains(e.target)) {
+                setOpen(false);
+            }
+        };
+        const handleEscape = (e) => {
+            if (e.key === 'Escape') {
+                setOpen(false);
+            }
+        };
+        document.addEventListener('mousedown', handleClickOutside);
+        document.addEventListener('keydown', handleEscape);
+        return () => {
+            document.removeEventListener('mousedown', handleClickOutside);
+            document.removeEventListener('keydown', handleEscape);
+        };
+    }, [open]);
+    // ---------------------------------------------------------------------------
+    // Selection handler
+    // ---------------------------------------------------------------------------
+    const handleSelect = useCallback((value) => {
+        log.verbose('FacetDropdown: Value selected', { field, value });
+        // Update internal state
+        setInternalValue(value);
+        setOpen(false);
+        // Call onChange callback
+        if (onChange) {
+            onChange(value);
+        }
+        // Apply filter if enabled and we have search state
+        if (applyFilter && addRefinement && removeRefinement) {
+            // Remove any existing refinement for this field
+            const existingRefinement = refinements.find(r => r.field === field);
+            if (existingRefinement) {
+                removeRefinement(field, existingRefinement.value, false);
+            }
+            // Add new refinement if value is not empty
+            if (value) {
+                addRefinement(field, value, true); // true = trigger search
+            }
+            else if (search) {
+                // If clearing the filter, trigger search manually
+                search();
+            }
+        }
+        // Navigate to search page if enabled
+        if (navigateOnSelect && value && typeof window !== 'undefined') {
+            const url = new URL(window.location.origin + searchPageUrl);
+            url.searchParams.set(field, value);
+            window.location.href = url.toString();
+        }
+    }, [field, onChange, applyFilter, addRefinement, removeRefinement, refinements, search, navigateOnSelect, searchPageUrl]);
+    // ---------------------------------------------------------------------------
+    // Render
+    // ---------------------------------------------------------------------------
+    const displayLabel = currentValue || placeholder;
+    const hasOptions = facetOptions.length > 0;
+    const buttonClass = [
+        'facet-dropdown-button',
+        customTheme.button,
+        className,
+        open && customTheme.buttonOpen,
+    ]
+        .filter(Boolean)
+        .join(' ');
+    // Render dropdown panel via portal
+    const renderDropdown = () => {
+        if (!open || !hasOptions || !dropdownPosition || typeof document === 'undefined') {
+            return null;
+        }
+        const dropdown = (React.createElement("div", { ref: dropdownRef, className: customTheme.panel || 'facet-dropdown-panel', role: "listbox", "aria-label": `${field} options`, style: {
+                position: 'absolute',
+                top: `${dropdownPosition.top}px`,
+                left: `${dropdownPosition.left}px`,
+                minWidth: `${dropdownPosition.width}px`,
+                width: 'max-content',
+                maxWidth: 'min(24rem, 90vw)',
+                maxHeight: `calc(100vh - 100px)`,
+                overflowY: 'auto',
+                overflowX: 'hidden',
+                backgroundColor: 'var(--facet-dropdown-bg, var(--background))',
+                border: '1px solid var(--facet-dropdown-border, var(--border-color))',
+                borderRadius: theme?.borderRadius && typeof theme.borderRadius !== 'string'
+                    ? theme.borderRadius.medium
+                    : '0.5rem',
+                boxShadow: 'var(--facet-dropdown-shadow, var(--shadow-lg))',
+                zIndex: Z_INDEX.dropdown,
+                padding: '0.25rem',
+            } },
+            React.createElement("button", { type: "button", role: "option", "aria-selected": !currentValue, onClick: (e) => {
+                    e.preventDefault();
+                    e.stopPropagation();
+                    handleSelect('');
+                }, className: [
+                    customTheme.option,
+                    !currentValue && customTheme.optionActive,
+                ]
+                    .filter(Boolean)
+                    .join(' '), style: {
+                    width: '100%',
+                    textAlign: 'left',
+                    padding: '0.5rem 0.75rem',
+                    fontSize: 'var(--facet-dropdown-option-font-size, 0.875rem)',
+                    fontWeight: !currentValue ? 'var(--facet-dropdown-option-font-weight-active, 500)' : 'normal',
+                    color: 'var(--facet-dropdown-option-text, var(--text-color, currentColor))',
+                    backgroundColor: !currentValue ? 'var(--facet-dropdown-option-active-bg, var(--hover-color))' : 'transparent',
+                    border: 'none',
+                    borderRadius: theme?.borderRadius && typeof theme.borderRadius !== 'string'
+                        ? theme.borderRadius.small
+                        : '0.25rem',
+                    cursor: 'pointer',
+                    transition: 'background-color 0.15s ease',
+                    display: 'flex',
+                    alignItems: 'center',
+                    justifyContent: 'space-between',
+                } },
+                React.createElement("span", null, placeholder)),
+            facetOptions.map((option) => {
+                const isActive = currentValue === option.value;
+                return (React.createElement("button", { key: option.value, type: "button", role: "option", "aria-selected": isActive, onClick: (e) => {
+                        e.preventDefault();
+                        e.stopPropagation();
+                        handleSelect(option.value);
+                    }, className: [
+                        customTheme.option,
+                        isActive && customTheme.optionActive,
+                    ]
+                        .filter(Boolean)
+                        .join(' '), style: {
+                        width: '100%',
+                        textAlign: 'left',
+                        padding: '0.5rem 0.75rem',
+                        fontSize: 'var(--facet-dropdown-option-font-size, 0.875rem)',
+                        fontWeight: isActive ? 'var(--facet-dropdown-option-font-weight-active, 500)' : 'normal',
+                        color: 'var(--facet-dropdown-option-text, var(--text-color, currentColor))',
+                        backgroundColor: isActive ? 'var(--facet-dropdown-option-active-bg, var(--hover-color))' : 'transparent',
+                        border: 'none',
+                        borderRadius: theme?.borderRadius && typeof theme.borderRadius !== 'string'
+                            ? theme.borderRadius.small
+                            : '0.25rem',
+                        cursor: 'pointer',
+                        transition: 'background-color 0.15s ease',
+                        display: 'flex',
+                        alignItems: 'center',
+                        justifyContent: 'space-between',
+                    } },
+                    React.createElement("span", { style: { flex: 1, overflow: 'hidden', textOverflow: 'ellipsis' } }, option.label || option.value),
+                    showCounts && (React.createElement("span", { style: {
+                            fontSize: 'var(--facet-dropdown-count-font-size, 0.75rem)',
+                            color: 'var(--facet-dropdown-count-text, var(--text-secondary, currentColor))',
+                            opacity: 0.7,
+                            marginLeft: '0.5rem',
+                            flexShrink: 0,
+                        } },
+                        "(",
+                        option.count,
+                        ")"))));
+            })));
+        return createPortal(dropdown, document.body);
+    };
+    return (React.createElement("div", { className: "facet-dropdown-container", style: { position: 'relative' } },
+        React.createElement("style", { dangerouslySetInnerHTML: {
+                __html: `
+          .facet-dropdown-panel {
+            --scrollbar-track: transparent;
+            --scrollbar-thumb: var(--facet-dropdown-scrollbar-thumb, var(--border-color));
+            --scrollbar-thumb-hover: var(--facet-dropdown-scrollbar-thumb-hover, var(--text-secondary));
+          }
+          .facet-dropdown-panel::-webkit-scrollbar {
+            width: 6px;
+          }
+          .facet-dropdown-panel::-webkit-scrollbar-track {
+            background: var(--scrollbar-track);
+          }
+          .facet-dropdown-panel::-webkit-scrollbar-thumb {
+            background: var(--scrollbar-thumb);
+            border-radius: 3px;
+          }
+          .facet-dropdown-panel::-webkit-scrollbar-thumb:hover {
+            background: var(--scrollbar-thumb-hover);
+          }
+          .facet-dropdown-panel {
+            scrollbar-width: thin;
+            scrollbar-color: var(--scrollbar-thumb) var(--scrollbar-track);
+          }
+        `
+            } }),
+        React.createElement("button", { ref: buttonRef, type: "button", onClick: (e) => {
+                e.preventDefault();
+                e.stopPropagation();
+                setOpen(prev => !prev);
+            }, className: buttonClass, "aria-label": `Filter by ${field}`, "aria-expanded": open, "aria-haspopup": "listbox", style: {
+                display: 'flex',
+                alignItems: 'center',
+                gap: '0.375rem',
+                padding: '0.625rem 0.75rem',
+                fontSize: 'var(--facet-dropdown-font-size, 0.875rem)',
+                fontWeight: 'var(--facet-dropdown-font-weight, 500)',
+                color: 'var(--facet-dropdown-text, var(--text-color, currentColor))',
+                backgroundColor: 'var(--facet-dropdown-button-bg, var(--background, transparent))',
+                border: '1px solid var(--facet-dropdown-border, var(--border-color))',
+                borderRadius: theme?.borderRadius && typeof theme.borderRadius !== 'string'
+                    ? theme.borderRadius.medium
+                    : '0.5rem',
+                cursor: 'pointer',
+                transition: 'all 0.2s ease',
+                outline: 'none',
+                whiteSpace: 'nowrap',
+                minWidth: '8rem',
+                ...(!hasOptions && { opacity: 0.6, cursor: 'not-allowed' }),
+            }, disabled: !hasOptions },
+            React.createElement("span", { style: { flex: 1, textAlign: 'left', overflow: 'hidden', textOverflow: 'ellipsis' } }, displayLabel),
+            React.createElement("svg", { className: customTheme.caretIcon, width: "16", height: "16", viewBox: "0 0 16 16", fill: "none", xmlns: "http://www.w3.org/2000/svg", style: {
+                    transform: open ? 'rotate(180deg)' : 'rotate(0deg)',
+                    transition: 'transform 0.2s ease',
+                    flexShrink: 0,
+                }, "aria-hidden": "true" },
+                React.createElement("path", { d: "M4 6L8 10L12 6", stroke: "currentColor", strokeWidth: "1.5", strokeLinecap: "round", strokeLinejoin: "round" }))),
+        renderDropdown()));
+};

package/dist/components/Facets.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Facets Component
+ *
+ * Displays facet filters for search results with multiple display variants,
+ * client-side search, count badges, and color swatch support.
+ */
+import React from 'react';
+import type { SearchResponse } from '@seekora-ai/search-sdk';
+export interface FacetItem {
+    value: string;
+    count: number;
+    selected?: boolean;
+}
+export interface FacetStats {
+    min: number;
+    max: number;
+    avg?: number;
+    sum?: number;
+}
+export interface FacetRangeItem {
+    label: string;
+    from?: number;
+    to?: number;
+}
+export interface FacetRangeConfig {
+    field: string;
+    ranges: FacetRangeItem[];
+}
+export interface Facet {
+    field: string;
+    label?: string;
+    items: FacetItem[];
+    stats?: FacetStats;
+}
+export interface FacetsTheme {
+    container?: string;
+    facet?: string;
+    facetHeader?: string;
+    facetTitle?: string;
+    facetList?: string;
+    facetItem?: string;
+    facetItemActive?: string;
+    facetItemCount?: string;
+    facetItemLabel?: string;
+    checkbox?: string;
+    /** Color swatch circle/square */
+    colorSwatch?: string;
+    /** Color swatch when selected */
+    colorSwatchSelected?: string;
+    /** Inner element of color swatch (for checkmark overlay) */
+    colorSwatchInner?: string;
+    /** Search input within a facet group */
+    searchInput?: string;
+    /** Collapsible header row */
+    collapsibleHeader?: string;
+    /** Chevron/expand icon in collapsible header */
+    collapsibleIcon?: string;
+    /** Count badge pill */
+    countBadge?: string;
+    /** Range button (pre-configured range option) */
+    rangeButton?: string;
+    /** Active range button */
+    rangeButtonActive?: string;
+    /** Count badge on range button */
+    rangeButtonCount?: string;
+    /** Clear button for range filters */
+    rangeClear?: string;
+}
+export type FacetVariant = 'checkbox' | 'color-swatch' | 'collapsible';
+export type FacetSize = 'small' | 'medium' | 'large';
+export interface FacetsProps {
+    /** Search results response */
+    results?: SearchResponse | null;
+    /** Custom facets data */
+    facets?: Facet[];
+    /** Callback when facet is selected/deselected */
+    onFacetChange?: (field: string, value: string, selected: boolean) => void;
+    /** Custom render function for facet */
+    renderFacet?: (facet: Facet, index: number) => React.ReactNode;
+    /** Custom render function for facet item */
+    renderFacetItem?: (item: FacetItem, facet: Facet, index: number) => React.ReactNode;
+    /** Maximum number of items to show per facet */
+    maxItems?: number;
+    /** Show "Show more" button */
+    showMore?: boolean;
+    /** Custom className */
+    className?: string;
+    /** Custom styles */
+    style?: React.CSSProperties;
+    /** Custom theme */
+    theme?: FacetsTheme;
+    /** Display variant: checkbox (default), color-swatch, or collapsible */
+    variant?: FacetVariant;
+    /** When true, show a search input at the top of each facet group */
+    searchable?: boolean;
+    /** Show count badges (default: true) */
+    showCounts?: boolean;
+    /** Maps facet values to CSS colors (used by color-swatch variant) */
+    colorMap?: Record<string, string>;
+    /** For collapsible variant, whether facets start collapsed (default: false) */
+    defaultCollapsed?: boolean;
+    /** Size preset: small, medium (default), or large */
+    size?: FacetSize;
+    /** Pre-configured range button definitions for numeric facets */
+    facetRanges?: FacetRangeConfig[];
+    /** Use dedicated Filters API instead of extracting facets from search results */
+    useFiltersApi?: boolean;
+    /** Fields that should use disjunctive (OR) faceting (only with useFiltersApi) */
+    disjunctiveFacets?: string[];
+    /** Hide facets that have no selectable values (default: true) */
+    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;
+}
+export declare const Facets: React.FC<FacetsProps>;
+//# sourceMappingURL=Facets.d.ts.map

package/dist/components/Facets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Facets.d.ts","sourceRoot":"","sources":["../../src/components/Facets.tsx"],"names":[],"mappings":"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"}