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

package/dist/components/HierarchicalMenu.d.ts

@@ -0,0 +1,55 @@
+/**
+ * HierarchicalMenu Component
+ *
+ * Displays a hierarchical menu for nested category navigation
+ * Example: Electronics > Phones > iPhone
+ */
+import React from 'react';
+export interface HierarchicalMenuItem {
+    label: string;
+    value: string;
+    count?: number;
+    isRefined?: boolean;
+    data?: HierarchicalMenuItem[];
+}
+export interface HierarchicalMenuTheme {
+    root?: string;
+    list?: string;
+    item?: string;
+    itemSelected?: string;
+    itemParent?: string;
+    link?: string;
+    label?: string;
+    count?: string;
+    showMore?: string;
+}
+export interface HierarchicalMenuProps {
+    /** Attributes for each level of hierarchy (e.g., ['category.lvl0', 'category.lvl1', 'category.lvl2']) */
+    attributes: string[];
+    /** Separator used in the hierarchical values (default: ' > ') */
+    separator?: string;
+    /** Maximum number of items to show per level (default: 10) */
+    limit?: number;
+    /** Show "Show more" button (default: true) */
+    showMore?: boolean;
+    /** Maximum items when "Show more" is clicked (default: 20) */
+    showMoreLimit?: number;
+    /** Custom render function for items */
+    renderItem?: (item: HierarchicalMenuItem, level: number) => React.ReactNode;
+    /** Callback when an item is selected */
+    onSelect?: (value: string, level: number) => void;
+    /** Custom className */
+    className?: string;
+    /** Custom styles */
+    style?: React.CSSProperties;
+    /** Custom theme */
+    theme?: HierarchicalMenuTheme;
+    /** Root path (for pre-selecting a category) */
+    rootPath?: string | null;
+    /** Sort by (default: 'name') */
+    sortBy?: 'name' | 'count' | 'isRefined';
+    /** Custom facet data (if not using StateManager) */
+    items?: HierarchicalMenuItem[];
+}
+export declare const HierarchicalMenu: React.FC<HierarchicalMenuProps>;
+//# sourceMappingURL=HierarchicalMenu.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"HierarchicalMenu.d.ts","sourceRoot":"","sources":["../../src/components/HierarchicalMenu.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAiD,MAAM,OAAO,CAAC;AAKtE,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,IAAI,CAAC,EAAE,oBAAoB,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,yGAAyG;IACzG,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,8DAA8D;IAC9D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uCAAuC;IACvC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,oBAAoB,EAAE,KAAK,EAAE,MAAM,KAAK,KAAK,CAAC,SAAS,CAAC;IAC5E,wCAAwC;IACxC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClD,uBAAuB;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oBAAoB;IACpB,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAC5B,mBAAmB;IACnB,KAAK,CAAC,EAAE,qBAAqB,CAAC;IAC9B,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,gCAAgC;IAChC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,WAAW,CAAC;IACxC,oDAAoD;IACpD,KAAK,CAAC,EAAE,oBAAoB,EAAE,CAAC;CAChC;AAED,eAAO,MAAM,gBAAgB,EAAE,KAAK,CAAC,EAAE,CAAC,qBAAqB,CAoW5D,CAAC"}

package/dist/components/HierarchicalMenu.js

@@ -0,0 +1,276 @@
+/**
+ * HierarchicalMenu Component
+ *
+ * Displays a hierarchical menu for nested category navigation
+ * Example: Electronics > Phones > iPhone
+ */
+import React, { useState, useMemo, useCallback, useRef } from 'react';
+import { useSearchContext } from './SearchProvider';
+import { useSearchState } from '../hooks/useSearchState';
+import { clsx } from 'clsx';
+export const HierarchicalMenu = ({ attributes, separator = ' > ', limit = 10, showMore = true, showMoreLimit = 20, renderItem, onSelect, className, style, theme: customTheme, rootPath = null, sortBy = 'name', items: itemsProp, }) => {
+    const { theme, stateManager } = useSearchContext();
+    const { results, refinements, addRefinement, removeRefinement } = useSearchState();
+    const hierarchicalTheme = customTheme || {};
+    const [expanded, setExpanded] = useState({});
+    // Get hierarchical facet data from results
+    const getHierarchicalData = useCallback(() => {
+        if (itemsProp)
+            return itemsProp;
+        if (!results)
+            return [];
+        // Try to find hierarchical facet data in various response formats
+        const facets = results.facets || results.facet_counts || {};
+        // Build hierarchy from flat facet data
+        const rootAttribute = attributes[0];
+        const rootFacet = facets[rootAttribute] || {};
+        const items = [];
+        Object.entries(rootFacet).forEach(([value, count]) => {
+            const isRefined = refinements.some(r => r.field === rootAttribute && r.value === value);
+            items.push({
+                label: value,
+                value,
+                count: count,
+                isRefined,
+                data: getChildItems(value, 1),
+            });
+        });
+        return items;
+    }, [results, attributes, refinements, itemsProp]);
+    // Get child items for a parent value
+    const getChildItems = useCallback((parentValue, level) => {
+        if (level >= attributes.length)
+            return [];
+        if (!results)
+            return [];
+        const facets = results.facets || results.facet_counts || {};
+        const attribute = attributes[level];
+        const facet = facets[attribute] || {};
+        const items = [];
+        Object.entries(facet).forEach(([value, count]) => {
+            // Check if this item belongs to the parent
+            if (value.startsWith(parentValue + separator)) {
+                const label = value.replace(parentValue + separator, '').split(separator)[0];
+                const isRefined = refinements.some(r => r.field === attribute && r.value === value);
+                // Only add direct children
+                const remainingPath = value.replace(parentValue + separator, '');
+                if (!remainingPath.includes(separator)) {
+                    items.push({
+                        label,
+                        value,
+                        count: count,
+                        isRefined,
+                        data: getChildItems(value, level + 1),
+                    });
+                }
+            }
+        });
+        return items;
+    }, [results, attributes, separator, refinements]);
+    // Get sorted and limited items
+    const processedItems = useMemo(() => {
+        let items = getHierarchicalData();
+        // Sort
+        items = [...items].sort((a, b) => {
+            if (sortBy === 'count') {
+                return (b.count || 0) - (a.count || 0);
+            }
+            if (sortBy === 'isRefined') {
+                if (a.isRefined && !b.isRefined)
+                    return -1;
+                if (!a.isRefined && b.isRefined)
+                    return 1;
+            }
+            return a.label.localeCompare(b.label);
+        });
+        return items;
+    }, [getHierarchicalData, sortBy]);
+    // Handle item click
+    const handleItemClick = useCallback((item, level) => {
+        const attribute = attributes[level] || attributes[0];
+        if (item.isRefined) {
+            // Remove this and all child refinements
+            attributes.slice(level).forEach((attr) => {
+                refinements
+                    .filter(r => r.field === attr && r.value.startsWith(item.value))
+                    .forEach(r => removeRefinement(r.field, r.value, false));
+            });
+            stateManager.search();
+        }
+        else {
+            // Clear sibling refinements at this level
+            refinements
+                .filter(r => r.field === attribute && r.value !== item.value)
+                .forEach(r => removeRefinement(r.field, r.value, false));
+            // Add this refinement
+            addRefinement(attribute, item.value, true);
+        }
+        if (onSelect) {
+            onSelect(item.value, level);
+        }
+    }, [attributes, refinements, addRefinement, removeRefinement, stateManager, onSelect]);
+    // Toggle show more
+    const toggleShowMore = (level) => {
+        setExpanded(prev => ({ ...prev, [level]: !prev[level] }));
+    };
+    const containerRef = useRef(null);
+    // Collect all visible treeitem elements within the container
+    const getVisibleTreeItems = useCallback(() => {
+        if (!containerRef.current)
+            return [];
+        return Array.from(containerRef.current.querySelectorAll('[role="treeitem"]'));
+    }, []);
+    // Keyboard navigation handler for the tree
+    const handleKeyDown = useCallback((e) => {
+        const items = getVisibleTreeItems();
+        if (items.length === 0)
+            return;
+        const activeElement = document.activeElement;
+        // Find the treeitem that is or contains the active element
+        const currentItem = items.find(item => item === activeElement || item.contains(activeElement));
+        const currentIndex = currentItem ? items.indexOf(currentItem) : -1;
+        switch (e.key) {
+            case 'ArrowDown': {
+                e.preventDefault();
+                const nextIndex = currentIndex < items.length - 1 ? currentIndex + 1 : 0;
+                const button = items[nextIndex].querySelector('button');
+                if (button)
+                    button.focus();
+                else
+                    items[nextIndex].focus();
+                break;
+            }
+            case 'ArrowUp': {
+                e.preventDefault();
+                const prevIndex = currentIndex > 0 ? currentIndex - 1 : items.length - 1;
+                const button = items[prevIndex].querySelector('button');
+                if (button)
+                    button.focus();
+                else
+                    items[prevIndex].focus();
+                break;
+            }
+            case 'ArrowRight': {
+                if (!currentItem)
+                    break;
+                const isExpanded = currentItem.getAttribute('aria-expanded');
+                if (isExpanded === 'false') {
+                    // Expand (select) this item
+                    e.preventDefault();
+                    const button = currentItem.querySelector('button');
+                    if (button)
+                        button.click();
+                }
+                else if (isExpanded === 'true') {
+                    // Move to first child
+                    e.preventDefault();
+                    const childList = currentItem.querySelector('[role="group"]');
+                    if (childList) {
+                        const firstChild = childList.querySelector('[role="treeitem"]');
+                        if (firstChild) {
+                            const button = firstChild.querySelector('button');
+                            if (button)
+                                button.focus();
+                            else
+                                firstChild.focus();
+                        }
+                    }
+                }
+                break;
+            }
+            case 'ArrowLeft': {
+                if (!currentItem)
+                    break;
+                const isExpanded = currentItem.getAttribute('aria-expanded');
+                if (isExpanded === 'true') {
+                    // Collapse this item
+                    e.preventDefault();
+                    const button = currentItem.querySelector('button');
+                    if (button)
+                        button.click();
+                }
+                else {
+                    // Move focus to parent treeitem
+                    e.preventDefault();
+                    const parentGroup = currentItem.closest('[role="group"]');
+                    if (parentGroup) {
+                        const parentItem = parentGroup.closest('[role="treeitem"]');
+                        if (parentItem) {
+                            const button = parentItem.querySelector(':scope > button');
+                            if (button)
+                                button.focus();
+                            else
+                                parentItem.focus();
+                        }
+                    }
+                }
+                break;
+            }
+            case 'Enter': {
+                if (!currentItem)
+                    break;
+                e.preventDefault();
+                const button = currentItem.querySelector('button');
+                if (button)
+                    button.click();
+                break;
+            }
+            default:
+                break;
+        }
+    }, [getVisibleTreeItems]);
+    // Render a level of the hierarchy
+    const renderLevel = (items, level) => {
+        if (!items || items.length === 0)
+            return null;
+        const isExpanded = expanded[level] || false;
+        const displayLimit = isExpanded ? showMoreLimit : limit;
+        const displayItems = items.slice(0, displayLimit);
+        const hasMore = items.length > displayLimit;
+        return (React.createElement("ul", { role: level === 0 ? 'tree' : 'group', className: hierarchicalTheme.list, style: {
+                listStyle: 'none',
+                margin: 0,
+                padding: level > 0 ? `0 0 0 ${theme.spacing.medium}` : 0,
+            } },
+            displayItems.map((item, index) => (React.createElement("li", { key: item.value, role: "treeitem", ...(item.data && item.data.length > 0
+                    ? { 'aria-expanded': !!item.isRefined }
+                    : {}), className: clsx(hierarchicalTheme.item, item.isRefined && hierarchicalTheme.itemSelected, item.data && item.data.length > 0 && hierarchicalTheme.itemParent), style: {
+                    padding: `${theme.spacing.small} 0`,
+                } }, renderItem ? (renderItem(item, level)) : (React.createElement(React.Fragment, null,
+                React.createElement("button", { type: "button", onClick: () => handleItemClick(item, level), className: hierarchicalTheme.link, style: {
+                        display: 'flex',
+                        alignItems: 'center',
+                        gap: theme.spacing.small,
+                        width: '100%',
+                        padding: 0,
+                        background: 'none',
+                        border: 'none',
+                        cursor: 'pointer',
+                        textAlign: 'left',
+                        fontFamily: 'inherit',
+                        fontSize: theme.typography.fontSize.small,
+                        color: item.isRefined ? theme.colors.primary : theme.colors.text,
+                        fontWeight: item.isRefined ? 600 : 400,
+                    } },
+                    React.createElement("span", { className: hierarchicalTheme.label, style: { flex: 1 } }, item.label),
+                    item.count !== undefined && (React.createElement("span", { className: hierarchicalTheme.count, style: {
+                            color: theme.colors.textSecondary,
+                            fontSize: theme.typography.fontSize.small,
+                        } }, item.count))),
+                item.isRefined && item.data && item.data.length > 0 && (renderLevel(item.data, level + 1))))))),
+            showMore && hasMore && (React.createElement("li", null,
+                React.createElement("button", { type: "button", onClick: () => toggleShowMore(level), className: hierarchicalTheme.showMore, style: {
+                        padding: `${theme.spacing.small} 0`,
+                        background: 'none',
+                        border: 'none',
+                        cursor: 'pointer',
+                        fontSize: theme.typography.fontSize.small,
+                        color: theme.colors.primary,
+                        textDecoration: 'underline',
+                    } }, isExpanded ? 'Show less' : `Show ${items.length - displayLimit} more`)))));
+    };
+    if (processedItems.length === 0) {
+        return null;
+    }
+    return (React.createElement("div", { ref: containerRef, className: clsx(hierarchicalTheme.root, className), style: style, tabIndex: 0, onKeyDown: handleKeyDown }, renderLevel(processedItems, 0)));
+};

package/dist/components/Highlight.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Highlight Component
+ *
+ * Renders highlighted search result text with matching terms emphasized
+ */
+import React from 'react';
+import { HighlightPart } from '@seekora-ai/ui-sdk-core';
+export interface HighlightTheme {
+    root?: string;
+    highlighted?: string;
+    nonHighlighted?: string;
+}
+export interface HighlightProps {
+    /** The search hit containing highlight data */
+    hit: Record<string, any>;
+    /** The attribute to highlight */
+    attribute: string;
+    /** Custom className */
+    className?: string;
+    /** Custom styles */
+    style?: React.CSSProperties;
+    /** Custom theme */
+    theme?: HighlightTheme;
+    /** Tag name for root element (default: 'span') */
+    tagName?: keyof JSX.IntrinsicElements;
+    /** Custom render for highlighted parts */
+    renderHighlighted?: (part: HighlightPart, index: number) => React.ReactNode;
+    /** Custom render for non-highlighted parts */
+    renderNonHighlighted?: (part: HighlightPart, index: number) => React.ReactNode;
+    /** Fallback query for client-side highlighting (when server highlight not available) */
+    query?: string;
+}
+export declare const Highlight: React.FC<HighlightProps>;
+/**
+ * Snippet Component
+ *
+ * Renders a truncated, highlighted excerpt from search results
+ */
+export interface SnippetTheme extends HighlightTheme {
+    ellipsis?: string;
+}
+export interface SnippetProps extends Omit<HighlightProps, 'theme'> {
+    /** Maximum length of snippet (default: 100) */
+    maxLength?: number;
+    /** Ellipsis to use when truncating (default: '...') */
+    ellipsis?: string;
+    /** Custom theme */
+    theme?: SnippetTheme;
+}
+export declare const Snippet: React.FC<SnippetProps>;
+//# sourceMappingURL=Highlight.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Highlight.d.ts","sourceRoot":"","sources":["../../src/components/Highlight.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAkB,MAAM,OAAO,CAAC;AAEvC,OAAO,EAIL,aAAa,EACd,MAAM,yBAAyB,CAAC;AAEjC,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,cAAc;IAC7B,+CAA+C;IAC/C,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACzB,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,uBAAuB;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oBAAoB;IACpB,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAC5B,mBAAmB;IACnB,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,GAAG,CAAC,iBAAiB,CAAC;IACtC,0CAA0C;IAC1C,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,KAAK,KAAK,CAAC,SAAS,CAAC;IAC5E,8CAA8C;IAC9C,oBAAoB,CAAC,EAAE,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,KAAK,KAAK,CAAC,SAAS,CAAC;IAC/E,wFAAwF;IACxF,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,SAAS,EAAE,KAAK,CAAC,EAAE,CAAC,cAAc,CA8E9C,CAAC;AAEF;;;;GAIG;AAEH,MAAM,WAAW,YAAa,SAAQ,cAAc;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAa,SAAQ,IAAI,CAAC,cAAc,EAAE,OAAO,CAAC;IACjE,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mBAAmB;IACnB,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB;AAED,eAAO,MAAM,OAAO,EAAE,KAAK,CAAC,EAAE,CAAC,YAAY,CA2G1C,CAAC"}

package/dist/components/Highlight.js

@@ -0,0 +1,155 @@
+/**
+ * Highlight Component
+ *
+ * Renders highlighted search result text with matching terms emphasized
+ */
+import React, { useMemo } from 'react';
+import { useSearchContext } from './SearchProvider';
+import { getHighlightedValue, parseHighlightedParts, parseQueryHighlightParts, } from '@seekora-ai/ui-sdk-core';
+export const Highlight = ({ hit, attribute, className, style, theme: customTheme, tagName: Tag = 'span', renderHighlighted, renderNonHighlighted, query, }) => {
+    const { theme } = useSearchContext();
+    const highlightTheme = customTheme || {};
+    // Get highlighted value from hit
+    const highlightedValue = useMemo(() => {
+        return getHighlightedValue({
+            hit,
+            attribute,
+            preTag: '<mark>',
+            postTag: '</mark>',
+        });
+    }, [hit, attribute]);
+    // Parse into parts
+    const parts = useMemo(() => {
+        // First try server-provided highlights
+        const serverParts = parseHighlightedParts(highlightedValue, '<mark>', '</mark>');
+        // If no highlights found and we have a query, do client-side highlighting
+        if (serverParts.every((p) => !p.isHighlighted) && query) {
+            const plainValue = hit[attribute] || highlightedValue;
+            return parseQueryHighlightParts(String(plainValue), query);
+        }
+        return serverParts;
+    }, [highlightedValue, query, hit, attribute]);
+    // Default highlight style
+    const defaultHighlightStyle = {
+        backgroundColor: theme.colors.warning || '#fff59d',
+        fontWeight: theme.typography.fontWeight?.semibold || 600,
+        padding: '0 2px',
+        borderRadius: '2px',
+    };
+    // Render parts
+    const renderedParts = parts.map((part, index) => {
+        if (part.isHighlighted) {
+            if (renderHighlighted) {
+                return React.createElement(React.Fragment, { key: index }, renderHighlighted(part, index));
+            }
+            return (React.createElement("mark", { key: index, className: highlightTheme.highlighted, style: defaultHighlightStyle }, part.value));
+        }
+        if (renderNonHighlighted) {
+            return React.createElement(React.Fragment, { key: index }, renderNonHighlighted(part, index));
+        }
+        return (React.createElement("span", { key: index, className: highlightTheme.nonHighlighted }, part.value));
+    });
+    return (React.createElement(Tag, { className: className || highlightTheme.root, style: style }, renderedParts));
+};
+export const Snippet = ({ hit, attribute, maxLength = 100, ellipsis = '...', className, style, theme: customTheme, tagName: Tag = 'span', renderHighlighted, renderNonHighlighted, query, }) => {
+    const { theme } = useSearchContext();
+    const snippetTheme = customTheme || {};
+    // Get snippet or truncated highlighted value
+    const snippetValue = useMemo(() => {
+        // Check for server-provided snippet
+        const snippetResult = hit._snippetResult?.[attribute]?.value ||
+            hit.snippet_result?.[attribute]?.value ||
+            hit._snippet?.[attribute] ||
+            hit.snippet?.[attribute];
+        if (snippetResult) {
+            return snippetResult
+                .replace(/<em>/g, '<mark>')
+                .replace(/<\/em>/g, '</mark>');
+        }
+        // Fall back to highlighted value, truncated
+        let text = getHighlightedValue({
+            hit,
+            attribute,
+            preTag: '<mark>',
+            postTag: '</mark>',
+        });
+        // Remove tags for length calculation
+        const plainText = text.replace(/<\/?mark>/g, '');
+        if (plainText.length > maxLength) {
+            // Need to truncate while preserving tags
+            const truncated = truncateWithTags(text, maxLength);
+            return truncated + ellipsis;
+        }
+        return text;
+    }, [hit, attribute, maxLength, ellipsis]);
+    // Parse into parts
+    const parts = useMemo(() => {
+        const serverParts = parseHighlightedParts(snippetValue, '<mark>', '</mark>');
+        if (serverParts.every((p) => !p.isHighlighted) && query) {
+            const plainValue = hit[attribute] || snippetValue;
+            let text = String(plainValue);
+            if (text.length > maxLength) {
+                text = text.substring(0, maxLength) + ellipsis;
+            }
+            return parseQueryHighlightParts(text, query);
+        }
+        return serverParts;
+    }, [snippetValue, query, hit, attribute, maxLength, ellipsis]);
+    // Default highlight style
+    const defaultHighlightStyle = {
+        backgroundColor: theme.colors.warning || '#fff59d',
+        fontWeight: theme.typography.fontWeight?.semibold || 600,
+        padding: '0 2px',
+        borderRadius: '2px',
+    };
+    // Render parts
+    const renderedParts = parts.map((part, index) => {
+        if (part.isHighlighted) {
+            if (renderHighlighted) {
+                return React.createElement(React.Fragment, { key: index }, renderHighlighted(part, index));
+            }
+            return (React.createElement("mark", { key: index, className: snippetTheme.highlighted, style: defaultHighlightStyle }, part.value));
+        }
+        if (renderNonHighlighted) {
+            return React.createElement(React.Fragment, { key: index }, renderNonHighlighted(part, index));
+        }
+        return (React.createElement("span", { key: index, className: snippetTheme.nonHighlighted }, part.value));
+    });
+    return (React.createElement(Tag, { className: className || snippetTheme.root, style: style }, renderedParts));
+};
+/**
+ * Truncate text while preserving HTML tags
+ */
+function truncateWithTags(text, maxLength) {
+    let visibleLength = 0;
+    let result = '';
+    let inTag = false;
+    for (let i = 0; i < text.length; i++) {
+        const char = text[i];
+        if (char === '<') {
+            inTag = true;
+            result += char;
+        }
+        else if (char === '>') {
+            inTag = false;
+            result += char;
+        }
+        else if (inTag) {
+            result += char;
+        }
+        else {
+            if (visibleLength >= maxLength) {
+                break;
+            }
+            result += char;
+            visibleLength++;
+        }
+    }
+    // Close any unclosed tags
+    const openTags = result.match(/<mark>/g)?.length || 0;
+    const closeTags = result.match(/<\/mark>/g)?.length || 0;
+    for (let i = 0; i < openTags - closeTags; i++) {
+        result += '</mark>';
+    }
+    return result;
+}

package/dist/components/HitsPerPage.d.ts

@@ -0,0 +1,41 @@
+/**
+ * HitsPerPage Component
+ *
+ * A dropdown to let users change the number of displayed hits per page
+ * Integrates with SearchStateManager for automatic state sync
+ */
+import React from 'react';
+export interface HitsPerPageItem {
+    value: number;
+    label: string;
+    default?: boolean;
+}
+export interface HitsPerPageTheme {
+    root?: string;
+    select?: string;
+    option?: string;
+}
+export interface HitsPerPageProps {
+    /** Available items per page options */
+    items: HitsPerPageItem[];
+    /** Callback when hits per page changes */
+    onHitsPerPageChange?: (value: number) => void;
+    /** Custom render function for select */
+    renderSelect?: (props: {
+        value: number;
+        onChange: (e: React.ChangeEvent<HTMLSelectElement>) => void;
+        items: HitsPerPageItem[];
+    }) => React.ReactNode;
+    /** Custom className */
+    className?: string;
+    /** Custom styles */
+    style?: React.CSSProperties;
+    /** Custom theme */
+    theme?: HitsPerPageTheme;
+    /** Label text before the select */
+    label?: string;
+    /** Whether to sync with SearchStateManager (default: true) */
+    syncWithState?: boolean;
+}
+export declare const HitsPerPage: React.FC<HitsPerPageProps>;
+//# sourceMappingURL=HitsPerPage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"HitsPerPage.d.ts","sourceRoot":"","sources":["../../src/components/HitsPerPage.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAiC,MAAM,OAAO,CAAC;AAMtD,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,uCAAuC;IACvC,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,0CAA0C;IAC1C,mBAAmB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9C,wCAAwC;IACxC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE;QACrB,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,WAAW,CAAC,iBAAiB,CAAC,KAAK,IAAI,CAAC;QAC5D,KAAK,EAAE,eAAe,EAAE,CAAC;KAC1B,KAAK,KAAK,CAAC,SAAS,CAAC;IACtB,uBAAuB;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oBAAoB;IACpB,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAC5B,mBAAmB;IACnB,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB,mCAAmC;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,eAAO,MAAM,WAAW,EAAE,KAAK,CAAC,EAAE,CAAC,gBAAgB,CA8GlD,CAAC"}

package/dist/components/HitsPerPage.js

@@ -0,0 +1,82 @@
+/**
+ * HitsPerPage Component
+ *
+ * A dropdown to let users change the number of displayed hits per page
+ * Integrates with SearchStateManager for automatic state sync
+ */
+import React, { useEffect } from 'react';
+import { useSearchContext } from './SearchProvider';
+import { useSearchState } from '../hooks/useSearchState';
+import { clsx } from 'clsx';
+import { CustomSelect } from './primitives/CustomSelect';
+export const HitsPerPage = ({ items, onHitsPerPageChange, renderSelect, className, style, theme: customTheme, label = 'Show', syncWithState = true, }) => {
+    const { theme } = useSearchContext();
+    const { itemsPerPage, setPage } = useSearchState();
+    const { stateManager } = useSearchContext();
+    const hitsPerPageTheme = customTheme || {};
+    // Find the default item or first item
+    const defaultItem = items.find(i => i.default) || items[0];
+    const [internalValue, setInternalValue] = React.useState(defaultItem?.value || 10);
+    // Initialize StateManager on mount if default is set
+    useEffect(() => {
+        if (syncWithState && defaultItem && itemsPerPage !== defaultItem.value) {
+            stateManager.setItemsPerPage(defaultItem.value, false);
+        }
+    }, []);
+    // Determine the current value from StateManager or internal
+    const value = syncWithState ? itemsPerPage : internalValue;
+    const handleChange = (e) => {
+        const newValue = parseInt(e.target.value, 10);
+        setInternalValue(newValue);
+        // Update StateManager
+        if (syncWithState) {
+            stateManager.setItemsPerPage(newValue, false);
+            // Reset to page 1 when changing items per page
+            setPage(1, true);
+        }
+        // Call callback
+        if (onHitsPerPageChange) {
+            onHitsPerPageChange(newValue);
+        }
+    };
+    // Custom render function
+    if (renderSelect) {
+        return (React.createElement("div", { className: clsx(hitsPerPageTheme.root, className), style: style }, renderSelect({
+            value,
+            onChange: handleChange,
+            items,
+        })));
+    }
+    return (React.createElement("div", { className: clsx(hitsPerPageTheme.root, className), style: {
+            display: 'flex',
+            alignItems: 'center',
+            gap: theme.spacing.small,
+            ...style,
+        } },
+        label && (React.createElement("label", { style: {
+                fontSize: theme.typography.fontSize.medium,
+                color: theme.colors.text,
+            } }, label)),
+        React.createElement(CustomSelect, { value: String(value), onChange: (val) => {
+                const newValue = parseInt(val, 10);
+                setInternalValue(newValue);
+                if (syncWithState) {
+                    stateManager.setItemsPerPage(newValue, false);
+                    setPage(1, true);
+                }
+                if (onHitsPerPageChange) {
+                    onHitsPerPageChange(newValue);
+                }
+            }, options: items.map((item) => ({
+                value: String(item.value),
+                label: item.label,
+            })), "aria-label": "Results per page", className: hitsPerPageTheme.select, style: {
+                '--seekora-select-font-size': theme.typography.fontSize.medium,
+                '--seekora-select-border': theme.colors.border,
+                '--seekora-select-radius': typeof theme.borderRadius === 'string'
+                    ? theme.borderRadius
+                    : theme.borderRadius.medium,
+                '--seekora-select-bg': theme.colors.background,
+                '--seekora-select-color': theme.colors.text,
+            } })));
+};