@constructor-io/constructorio-ui-asa 1.0.0

package/lib/mjs/hooks/useAsaResults.js

@@ -0,0 +1,118 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useCioAsaContext } from './useCioAsaContext';
+import { handleSearchResult, handleMessage, handleServerError, handleStreamEnd, handleStreamError, } from './asaStreamHandlers';
+export default function useAsaResults() {
+    const [messages, setMessages] = useState([]);
+    const [isStreaming, setIsStreaming] = useState(false);
+    const isStreamingRef = useRef(false);
+    const killSwitchRef = useRef(false);
+    const readerRef = useRef(null);
+    const threadIdRef = useRef(null);
+    const idCounterRef = useRef(0);
+    const contextValue = useCioAsaContext();
+    if (!contextValue) {
+        throw new Error('useAsaResults must be used within a CioAsaProvider.');
+    }
+    const { cioClient, staticRequestConfigs } = contextValue;
+    const { domain } = staticRequestConfigs || {};
+    if (!cioClient || !domain) {
+        throw new Error('useAsaResults requires a configured cioClient and domain. Check your CioAsaProvider props.');
+    }
+    const nextMessageId = useCallback(() => {
+        idCounterRef.current += 1;
+        return `msg-${idCounterRef.current}-${Date.now()}`;
+    }, []);
+    const sendMessage = useCallback((text) => {
+        if (!text.trim() || isStreamingRef.current)
+            return;
+        const userMessage = {
+            id: nextMessageId(),
+            role: 'user',
+            text: text.trim(),
+            status: 'done',
+        };
+        const assistantMessage = {
+            id: nextMessageId(),
+            role: 'assistant',
+            text: '',
+            groups: [],
+            status: 'loading',
+        };
+        setMessages((prev) => [...prev, userMessage, assistantMessage]);
+        setIsStreaming(true);
+        isStreamingRef.current = true;
+        killSwitchRef.current = false;
+        const stream = cioClient.agent.getAgentResultsStream(text.trim(), {
+            domain,
+            ...(threadIdRef.current && { threadId: threadIdRef.current }),
+        });
+        const reader = stream.getReader();
+        readerRef.current = reader;
+        (async () => {
+            let pendingGroup = null;
+            try {
+                // eslint-disable-next-line no-await-in-loop
+                while (!killSwitchRef.current) {
+                    // eslint-disable-next-line no-await-in-loop
+                    const res = await reader.read();
+                    if (killSwitchRef.current)
+                        break;
+                    if (res.done) {
+                        handleStreamEnd(assistantMessage.id, setMessages);
+                        break;
+                    }
+                    const { type, data } = res.value;
+                    if (type === 'start' && data?.thread_id) {
+                        threadIdRef.current = data.thread_id;
+                    }
+                    else if (type === 'group') {
+                        pendingGroup = {
+                            display_name: data?.display_name ?? data?.group ?? '',
+                            value: data?.value ?? data?.group ?? '',
+                        };
+                    }
+                    else if (type === 'search_result') {
+                        pendingGroup = handleSearchResult(data, pendingGroup, assistantMessage.id, setMessages);
+                    }
+                    else if (type === 'message') {
+                        handleMessage(data, assistantMessage.id, setMessages);
+                    }
+                    else if (type === 'server_error') {
+                        handleServerError(assistantMessage.id, setMessages);
+                        break;
+                    }
+                }
+            }
+            catch {
+                handleStreamError(assistantMessage.id, setMessages);
+            }
+            finally {
+                if (readerRef.current === reader) {
+                    reader.cancel();
+                    readerRef.current = null;
+                    setIsStreaming(false);
+                    isStreamingRef.current = false;
+                }
+            }
+        })();
+    }, [cioClient, domain, nextMessageId]);
+    useEffect(() => () => {
+        killSwitchRef.current = true;
+        if (readerRef.current) {
+            readerRef.current.cancel();
+            readerRef.current = null;
+        }
+    }, []);
+    const clearHistory = useCallback(() => {
+        killSwitchRef.current = true;
+        if (readerRef.current) {
+            readerRef.current.cancel();
+            readerRef.current = null;
+        }
+        threadIdRef.current = null;
+        setMessages([]);
+        setIsStreaming(false);
+        isStreamingRef.current = false;
+    }, []);
+    return { messages, sendMessage, isStreaming, clearHistory };
+}

package/lib/mjs/hooks/useCioAsaContext.js

@@ -0,0 +1,11 @@
+import { createContext, useContext } from 'react';
+export const AsaContext = createContext(null);
+AsaContext.displayName = 'AsaContext';
+/**
+ * React Hook to access state provided by CioAsa provider.
+ * Note: Should only be used by components nested under a CioAsa provider
+ */
+export function useCioAsaContext() {
+    return useContext(AsaContext);
+}
+export default useCioAsaContext;

package/lib/mjs/hooks/useCioClient.js

@@ -0,0 +1,23 @@
+import ConstructorIOClient from '@constructor-io/constructorio-client-javascript';
+import { useMemo } from 'react';
+import version from '../version';
+const useCioClient = ({ apiKey, cioClient, cioClientOptions } = {}) => {
+    if (!apiKey && !cioClient) {
+        throw new Error('Api Key or Constructor Client required');
+    }
+    const memoizedCioClient = useMemo(() => {
+        if (cioClient)
+            return cioClient;
+        if (apiKey && typeof window !== 'undefined') {
+            return new ConstructorIOClient({
+                apiKey,
+                sendTrackingEvents: true,
+                version: `cio-ui-asa-${version}`,
+                ...cioClientOptions,
+            });
+        }
+        return null;
+    }, [apiKey, cioClient, cioClientOptions]);
+    return memoizedCioClient;
+};
+export default useCioClient;

package/lib/mjs/hooks/useFocusTrap.js

@@ -0,0 +1,35 @@
+import { useEffect } from 'react';
+const FOCUSABLE_SELECTOR = 'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
+/**
+ * Traps Tab/Shift+Tab focus within the referenced container and invokes
+ * onEscape when Escape is pressed.
+ */
+export default function useFocusTrap(containerRef, { onEscape } = {}) {
+    useEffect(() => {
+        const container = containerRef.current;
+        if (!container)
+            return undefined;
+        const handleKeyDown = (e) => {
+            if (e.key === 'Escape' && onEscape) {
+                onEscape();
+            }
+            if (e.key === 'Tab') {
+                const focusableElements = container.querySelectorAll(FOCUSABLE_SELECTOR);
+                if (focusableElements.length === 0)
+                    return;
+                const first = focusableElements[0];
+                const last = focusableElements[focusableElements.length - 1];
+                if (e.shiftKey && document.activeElement === first) {
+                    e.preventDefault();
+                    last.focus();
+                }
+                else if (!e.shiftKey && document.activeElement === last) {
+                    e.preventDefault();
+                    first.focus();
+                }
+            }
+        };
+        container.addEventListener('keydown', handleKeyDown);
+        return () => container.removeEventListener('keydown', handleKeyDown);
+    }, [containerRef, onEscape]);
+}

package/lib/mjs/hooks/useMessageInput.js

@@ -0,0 +1,19 @@
+import { useState } from 'react';
+export default function useMessageInput({ onSend, isDisabled = false, submitOnEnterOnly = false, }) {
+    const [value, setValue] = useState('');
+    const handleSubmit = () => {
+        if (isDisabled || !value.trim())
+            return;
+        onSend(value.trim());
+        setValue('');
+    };
+    const handleKeyDown = (e) => {
+        if (e.key !== 'Enter')
+            return;
+        if (submitOnEnterOnly && e.shiftKey)
+            return;
+        e.preventDefault();
+        handleSubmit();
+    };
+    return { value, setValue, handleSubmit, handleKeyDown };
+}

package/lib/mjs/hooks/useRequestConfigs.js

@@ -0,0 +1,24 @@
+import { useCioAsaContext } from './useCioAsaContext';
+export default function useRequestConfigs() {
+    const context = useCioAsaContext();
+    if (!context) {
+        throw new Error('This Hook needs to be called within the C.io ASA Context Provider.');
+    }
+    const { urlHelpers, staticRequestConfigs } = context;
+    const { getUrl, setUrl, getStateFromUrl, getUrlFromState } = urlHelpers;
+    const url = getUrl();
+    const urlRequestConfigs = url ? getStateFromUrl(url) : {};
+    const requestConfigs = { ...staticRequestConfigs, ...urlRequestConfigs };
+    const setRequestConfigs = (configsToUpdate) => {
+        const oldUrl = getUrl();
+        if (!oldUrl) {
+            throw new Error('getUrl returns undefined when attempting to call setRequestConfigs');
+        }
+        const urlObj = new URL(oldUrl);
+        const oldRequestConfigs = getStateFromUrl(oldUrl);
+        const newRequestConfigs = { ...oldRequestConfigs, ...configsToUpdate };
+        const newUrl = getUrlFromState(newRequestConfigs, urlObj);
+        setUrl(newUrl);
+    };
+    return { requestConfigs, setRequestConfigs };
+}

package/lib/mjs/index.js

@@ -0,0 +1,11 @@
+// Components
+export { default as CioAsaProvider } from './components/CioAsaProvider/CioAsaProvider';
+export { default as Chat } from './components/Chat/Chat';
+export { default as ResultsBlock } from './components/ResultsBlock/ResultsBlock';
+export { default as Button } from './components/Button/Button';
+// Hooks
+export { default as useAsaResults } from './hooks/useAsaResults';
+// Utils
+export { normalizeItemToProduct } from './utils/productNormalizer';
+// Re-exported client value from the JS client (used to construct/type a cioClient)
+export { ConstructorIOClient } from './types';

package/lib/mjs/styles.css

@@ -0,0 +1,34 @@
+@import '@constructor-io/constructorio-ui-components/styles.css';
+@import './components/Button/Button.css';
+@import './components/Chat/Chat.css';
+@import './components/Chat/ChatHeader.css';
+@import './components/Chat/WelcomeScreen.css';
+@import './components/Chat/ChatMessageList.css';
+@import './components/Chat/UserMessage.css';
+@import './components/Chat/AiMessage.css';
+@import './components/Chat/TypingIndicator.css';
+@import './components/Chat/ChatInput.css';
+@import './components/ResultsBlock/ResultsBlock.css';
+
+.cio-asa,
+.cio-asa * {
+  font-family: var(--cio-asa-font-family, 'Inter', sans-serif);
+}
+
+.cio-sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+.cio-asa button:focus-visible,
+.cio-asa [role='button']:focus-visible {
+  outline: 2px solid #A980FF;
+  outline-offset: 2px;
+}

package/lib/mjs/types.js

@@ -0,0 +1,2 @@
+import ConstructorIOClient from '@constructor-io/constructorio-client-javascript';
+export { ConstructorIOClient };

package/lib/mjs/utils/formatters.js

@@ -0,0 +1,7 @@
+// eslint-disable-next-line import/prefer-default-export
+export function formatPrice(price) {
+    if (price) {
+        return `$${price.toFixed(2)}`;
+    }
+    return '';
+}

package/lib/mjs/utils/productNormalizer.js

@@ -0,0 +1,15 @@
+export function normalizeItemToProduct(item, options) {
+    const data = item.data || {};
+    return {
+        id: String(data.id ?? data.result_id ?? item.value ?? ''),
+        name: String(item.value ?? data.item_name ?? ''),
+        url: data.url,
+        imageUrl: data.image_url ?? data.imageUrl,
+        price: data.price,
+        salePrice: data.sale_price ?? data.salePrice,
+        description: data.description,
+        badge: data.sale_price != null || data.salePrice != null
+            ? options?.saleBadgeText ?? 'Sale'
+            : undefined,
+    };
+}

package/lib/mjs/utils/translate.js

@@ -0,0 +1,26 @@
+const defaultTranslations = {
+    'CioAsa.header.title': 'Shopping Assistant',
+    'CioAsa.header.close': 'Close',
+    'CioAsa.input.placeholder': 'Ask a question about this product',
+    'CioAsa.input.ariaLabel': 'Type your message',
+    'CioAsa.input.sendAriaLabel': 'Send message',
+    'CioAsa.welcome.title': 'Shopping Assistant',
+    'CioAsa.welcome.placeholder': 'Ask anything',
+    'CioAsa.welcome.sendButton': 'Chat',
+    'CioAsa.welcome.inputAriaLabel': 'Type your question',
+    'CioAsa.welcome.sendAriaLabel': 'Send message',
+    'CioAsa.welcome.suggestionsAriaLabel': 'Suggested questions',
+    'CioAsa.messageList.ariaLabel': 'Chat messages',
+    'CioAsa.typingIndicator.ariaLabel': 'Assistant is typing',
+    'CioAsa.userMessage.ariaLabel': 'You said',
+    'CioAsa.results.viewMore': 'View more products',
+    'CioAsa.results.addToCart': 'Add to cart',
+    'CioAsa.results.saleBadge': 'Sale',
+    'CioAsa.error.message': "I can't assist you with that request.",
+};
+export default function translate(key, translations) {
+    if (translations?.[key] !== undefined) {
+        return translations[key];
+    }
+    return defaultTranslations[key] ?? key;
+}

package/lib/mjs/utils/typeHelpers.js

@@ -0,0 +1 @@
+export {};

package/lib/mjs/utils/urlHelpers.js

@@ -0,0 +1,90 @@
+export const defaultQueryStringMap = Object.freeze({
+    intent: 'q',
+    page: 'page',
+    numResultsPerPage: 'resultsPerPod',
+    domain: 'domain',
+    filters: 'filters', // do special encoding/decoding
+});
+export function getUrl() {
+    if (typeof window === 'undefined')
+        return undefined;
+    return window.location.href;
+}
+export function setUrl(newUrlWithEncodedState) {
+    if (typeof window === 'undefined')
+        return;
+    window.location.href = newUrlWithEncodedState;
+}
+export function extractFiltersFromUrl(urlParams) {
+    const filters = {};
+    const filterRegex = new RegExp(`^${defaultQueryStringMap.filters}\\[(.*)\\]`);
+    urlParams?.forEach((value, key) => {
+        const filterKey = key?.match(filterRegex)?.[1];
+        if (filterKey) {
+            if (filters[filterKey]) {
+                filters[filterKey].push(value);
+            }
+            else {
+                filters[filterKey] = [value];
+            }
+        }
+    });
+    return Object.keys(filters).length ? filters : undefined;
+}
+export function getFilterParamsFromState(urlParams, filters) {
+    if (filters) {
+        Object.entries(filters)?.forEach(([filterName, filterValues]) => {
+            if (Array.isArray(filterValues)) {
+                filterValues.forEach((filterValue) => {
+                    urlParams.append(`filters[${filterName}]`, String(filterValue));
+                });
+            }
+            else {
+                urlParams.append(`filters[${filterName}]`, String(filterValues));
+            }
+        });
+    }
+}
+export function getStateFromUrl(url) {
+    const urlObject = new URL(url);
+    const urlParams = urlObject.searchParams;
+    const rawState = {};
+    Object.entries(defaultQueryStringMap).forEach(([key, val]) => {
+        const storedVal = urlParams.get(val);
+        if (storedVal != null) {
+            rawState[key] = storedVal;
+        }
+    });
+    const filters = extractFiltersFromUrl(urlParams);
+    const { page, numResultsPerPage, ...rest } = rawState;
+    const state = { ...rest };
+    if (numResultsPerPage)
+        state.numResultsPerPage = Number(numResultsPerPage);
+    if (filters)
+        state.filters = filters;
+    return state;
+}
+export function getUrlFromState(state, options = {}) {
+    const { baseUrl: url, origin, pathname } = options;
+    const baseUrl = url || `${origin}${pathname}`;
+    const params = new URLSearchParams();
+    Object.entries(state).forEach(([key, val]) => {
+        if (defaultQueryStringMap[key] === undefined) {
+            return;
+        }
+        let encodedVal = '';
+        if (key === 'filters' && state.filters) {
+            getFilterParamsFromState(params, state.filters);
+        }
+        else if (typeof val !== 'string') {
+            encodedVal = JSON.stringify(val);
+        }
+        else {
+            encodedVal = val;
+        }
+        if (encodedVal) {
+            params.set(defaultQueryStringMap[key], encodedVal);
+        }
+    });
+    return `${baseUrl}?${params.toString()}`;
+}

package/lib/mjs/version.js

@@ -0,0 +1 @@
+export default '1.0.0';

package/lib/types/components/Button/Button.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+export interface ButtonProps {
+    /** Color scheme: dark (for light backgrounds) or light (for dark backgrounds) */
+    theme?: 'dark' | 'light';
+    /** Button size: sm (small) or lg (large) */
+    size?: 'sm' | 'lg';
+    /** Click handler */
+    onClick?: () => void;
+    /** Button label text */
+    label?: string;
+}
+export default function Button({ theme, size, onClick, label, }: ButtonProps): React.JSX.Element;

package/lib/types/components/Chat/AiMessage.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+import { AiMessageOverrides, ChatMessage, Translations } from '../../types';
+export interface AiMessageProps {
+    message: ChatMessage;
+    componentOverrides?: AiMessageOverrides;
+    translations?: Translations;
+}
+declare function AiMessage({ message, componentOverrides, translations }: AiMessageProps): React.JSX.Element;
+declare namespace AiMessage {
+    var displayName: string;
+}
+export default AiMessage;

package/lib/types/components/Chat/Chat.d.ts

@@ -0,0 +1,38 @@
+import React from 'react';
+import { ChatComponentOverrides, ResultGroupMeta, Translations } from '../../types';
+import { Product, NormalizeOptions } from '../../utils/productNormalizer';
+import { AspectRatio } from '../ResultsBlock/ResultsBlock';
+export interface ChatHandle {
+    clearHistory: () => void;
+}
+interface ChatProps {
+    /** Called when the close button (✕) is clicked. The consumer controls visibility. */
+    onClose?: () => void;
+    /** Additional CSS class name for the root container */
+    className?: string;
+    /** Suggestion chips shown on the welcome screen */
+    initialSuggestions?: string[];
+    /** Legal/terms text displayed below the welcome screen input */
+    termsText?: React.ReactNode;
+    /** Called when a product card is clicked */
+    onProductClick?: (product: Product) => void;
+    /** Called when "View more" link is clicked in a results group */
+    onViewMore?: (group: ResultGroupMeta) => void;
+    /** Called when "Add to cart" button is clicked. If not provided, the button is hidden. */
+    onAddToCart?: (product: Product) => void;
+    /** Image aspect ratio for product cards */
+    aspectRatio?: AspectRatio;
+    /** Currency symbol for product prices */
+    currency?: string;
+    /**
+     * Map a raw search-result item to the `Product` shape rendered by result cards.
+     * Override this when your index metadata uses non-default field names.
+     */
+    normalizeItem?: (item: any, options?: NormalizeOptions) => Product;
+    /** Override any sub-component with custom render props or React nodes */
+    componentOverrides?: ChatComponentOverrides;
+    /** Translation overrides for internationalizing UI strings */
+    translations?: Translations;
+}
+declare const Chat: React.ForwardRefExoticComponent<ChatProps & React.RefAttributes<ChatHandle>>;
+export default Chat;

package/lib/types/components/Chat/ChatHeader.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+import { ChatHeaderRenderProps, ComponentOverrideProps, Translations } from '../../types';
+interface ChatHeaderProps {
+    onClose?: () => void;
+    translations?: Translations;
+    componentOverrides?: ComponentOverrideProps<ChatHeaderRenderProps>;
+}
+declare function ChatHeader({ onClose, translations, componentOverrides }: ChatHeaderProps): React.JSX.Element;
+declare namespace ChatHeader {
+    var displayName: string;
+}
+export default ChatHeader;

package/lib/types/components/Chat/ChatInput.d.ts

@@ -0,0 +1,13 @@
+import React from 'react';
+import { ChatInputRenderProps, ComponentOverrideProps, Translations } from '../../types';
+interface ChatInputProps {
+    onSubmit: (text: string) => void;
+    isDisabled?: boolean;
+    translations?: Translations;
+    componentOverrides?: ComponentOverrideProps<ChatInputRenderProps>;
+}
+declare function ChatInput({ onSubmit, isDisabled, translations, componentOverrides, }: ChatInputProps): React.JSX.Element;
+declare namespace ChatInput {
+    var displayName: string;
+}
+export default ChatInput;

package/lib/types/components/Chat/ChatMessageList.d.ts

@@ -0,0 +1,24 @@
+import React from 'react';
+import { AiMessageOverrides, ChatMessage, ComponentOverrideProps, ResultGroupMeta, ResultsBlockOverrides, Translations, UserMessageRenderProps } from '../../types';
+import { Product, NormalizeOptions } from '../../utils/productNormalizer';
+import { AspectRatio } from '../ResultsBlock/ResultsBlock';
+interface ChatMessageListProps {
+    messages: ChatMessage[];
+    onProductClick?: (product: Product) => void;
+    onViewMore?: (group: ResultGroupMeta) => void;
+    onAddToCart?: (product: Product) => void;
+    aspectRatio?: AspectRatio;
+    currency?: string;
+    normalizeItem?: (item: any, options?: NormalizeOptions) => Product;
+    addToCartText?: string;
+    viewMoreText?: string;
+    aiMessageOverrides?: AiMessageOverrides;
+    userMessageOverrides?: ComponentOverrideProps<UserMessageRenderProps>;
+    resultsBlockOverrides?: ResultsBlockOverrides;
+    translations?: Translations;
+}
+declare function ChatMessageList({ messages, onProductClick, onViewMore, onAddToCart, aspectRatio, currency, normalizeItem, addToCartText, viewMoreText, aiMessageOverrides, userMessageOverrides, resultsBlockOverrides, translations, }: ChatMessageListProps): React.JSX.Element;
+declare namespace ChatMessageList {
+    var displayName: string;
+}
+export default ChatMessageList;

package/lib/types/components/Chat/TypingIndicator.d.ts

@@ -0,0 +1,10 @@
+import React from 'react';
+import { Translations } from '../../types';
+interface TypingIndicatorProps {
+    translations?: Translations;
+}
+declare function TypingIndicator({ translations }: TypingIndicatorProps): React.JSX.Element;
+declare namespace TypingIndicator {
+    var displayName: string;
+}
+export default TypingIndicator;

package/lib/types/components/Chat/UserMessage.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+import { ComponentOverrideProps, Translations, UserMessageRenderProps } from '../../types';
+interface UserMessageProps {
+    text: string;
+    translations?: Translations;
+    componentOverrides?: ComponentOverrideProps<UserMessageRenderProps>;
+}
+declare function UserMessage({ text, translations, componentOverrides }: UserMessageProps): React.JSX.Element;
+declare namespace UserMessage {
+    var displayName: string;
+}
+export default UserMessage;

package/lib/types/components/Chat/WelcomeScreen.d.ts

@@ -0,0 +1,16 @@
+import React from 'react';
+import { Translations, WelcomeScreenOverrides } from '../../types';
+interface WelcomeScreenProps {
+    suggestions?: string[];
+    onSend: (text: string) => void;
+    onClose?: () => void;
+    termsText?: React.ReactNode;
+    disabled?: boolean;
+    translations?: Translations;
+    componentOverrides?: WelcomeScreenOverrides;
+}
+declare function WelcomeScreen({ suggestions, onSend, onClose, termsText, disabled, translations, componentOverrides, }: WelcomeScreenProps): React.JSX.Element;
+declare namespace WelcomeScreen {
+    var displayName: string;
+}
+export default WelcomeScreen;

package/lib/types/components/CioAsaProvider/CioAsaProvider.d.ts

@@ -0,0 +1,3 @@
+import React from 'react';
+import { AsaContextValue, IncludeRenderProps, CioAsaProviderProps } from '../../types';
+export default function CioAsaProvider(props: IncludeRenderProps<CioAsaProviderProps, AsaContextValue>): React.JSX.Element;

package/lib/types/components/ResultsBlock/ResultsBlock.d.ts

@@ -0,0 +1,32 @@
+import React from 'react';
+import { ResultGroup, ResultGroupMeta, ResultsBlockOverrides } from '../../types';
+import { Product, NormalizeOptions } from '../../utils/productNormalizer';
+import { AspectRatio } from './constants';
+import './ResultsBlock.css';
+export type { AspectRatio } from './constants';
+interface ResultsBlockProps {
+    groups: ResultGroup[];
+    aspectRatio?: AspectRatio;
+    minCardWidth?: number;
+    gap?: number;
+    showTitle?: boolean;
+    viewMoreText?: string;
+    addToCartText?: string;
+    saleBadgeText?: string;
+    currency?: string;
+    /**
+     * Map a raw search-result item to the `Product` shape rendered by the card.
+     * Override this when your index metadata uses non-default field names
+     * (e.g. `imageUrl` instead of `image_url`). Defaults to `normalizeItemToProduct`.
+     */
+    normalizeItem?: (item: any, options?: NormalizeOptions) => Product;
+    onProductClick?: (product: Product) => void;
+    onAddToCart?: (product: Product) => void;
+    onViewMore?: (group: ResultGroupMeta) => void;
+    componentOverrides?: ResultsBlockOverrides;
+}
+declare function ResultsBlock({ groups, aspectRatio, minCardWidth, gap, showTitle, viewMoreText, addToCartText, saleBadgeText, currency, normalizeItem, onProductClick, onAddToCart, onViewMore, componentOverrides, }: ResultsBlockProps): React.JSX.Element | null;
+declare namespace ResultsBlock {
+    var displayName: string;
+}
+export default ResultsBlock;

package/lib/types/components/ResultsBlock/constants.d.ts

@@ -0,0 +1,3 @@
+export type AspectRatio = '1:1' | '3:4' | '9:16' | '4:3' | '16:9';
+export declare const PEEK_FRACTION = 0.3;
+export declare const aspectRatioMap: Record<AspectRatio, string>;

package/lib/types/components/ResultsBlock/renderProductCard.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+import type { ProductCardProps, ProductCardOverrides } from '@constructor-io/constructorio-ui-components';
+import { Product } from '../../utils/productNormalizer';
+interface ProductCardRendererOptions {
+    currency?: string;
+    addToCartText?: string;
+    onProductClick?: (product: Product) => void;
+    onAddToCart?: (product: Product) => void;
+    componentOverrides?: ProductCardOverrides;
+}
+export default function createProductCardRenderer({ currency, addToCartText, onProductClick, onAddToCart, componentOverrides, }: ProductCardRendererOptions): (renderProps: ProductCardProps) => React.JSX.Element;
+export {};