@constructor-io/constructorio-ui-pia 2.3.0 → 2.6.2

package/lib/mjs/components/CioPia/CioPia.js

@@ -1,16 +1,14 @@
 import React from 'react';
 import { RenderPropsWrapper, } from '@constructor-io/constructorio-ui-components';
-import Disclaimer from './Disclaimer';
 import Input from '../Input/Input';
 import SuggestedQuestionsContainer from '../SuggestedQuestionsContainer/SuggestedQuestionsContainer';
-import Answer from '../Answer/Answer';
-import Feedback from '../Feedback/Feedback';
 import useCioPia from '../../hooks/useCioPia';
 import useConversation from '../../hooks/useConversation';
+import useViewportCallbacks from '../../hooks/useViewportCallbacks';
 import ErrorBlock from '../Error/ErrorBlock';
 import LoadingSkeleton from '../LoadingSkeleton/LoadingSkeleton';
 import { translate } from '../../utils/translate';
-import PiaCustomCarousel from './PiaCustomCarousel';
+import PiaInlineAnswer from '../PiaInlineAnswer/PiaInlineAnswer';
 import PiaModal from '../PiaConversation/PiaModal';
 import PiaConversation from '../PiaConversation/PiaConversation';
 export default function CioPia(props) {
@@ -26,7 +24,8 @@ export default function CioPia(props) {
         suggestedQuestionsParameters,
         formatImageUrl: formatters?.formatImageUrl,
     });
-    const { currentQuestion, displayedQuestions, conversationHistory, currentAnswer, currentItems, isLoading, error, handleSubmitQuestion, resetState, } = useConversation({ pia, itemId, isConversation, callbacks });
+    const { currentQuestion, displayedQuestions, conversationHistory, currentAnswer, currentItems, isLoading, error, context, handleSubmitQuestion, handleQuestionClick, handleInputFocus, resetState, } = useConversation({ pia, itemId, isConversation, callbacks });
+    const { containerRef } = useViewportCallbacks({ callbacks, context });
     const renderProps = {
         items: currentItems,
         isLoading,
@@ -51,27 +50,24 @@ export default function CioPia(props) {
         componentOverrides,
         displayedQuestions,
         handleSubmitQuestion,
+        handleQuestionClick,
+        containerRef,
+        onInputFocus: handleInputFocus,
     };
     if (type === 'modal') {
-        return (React.createElement(PiaModal, { initialQuestions: pia.suggestedQuestions.data, handleSubmitQuestion: handleSubmitQuestion, isLoading: isLoading, componentOverrides: componentOverrides, translations: translations, onClose: resetState },
+        return (React.createElement(PiaModal, { initialQuestions: pia.suggestedQuestions.data, handleSubmitQuestion: handleSubmitQuestion, handleQuestionClick: handleQuestionClick, containerRef: containerRef, isLoading: isLoading, componentOverrides: componentOverrides, translations: translations, onInputFocus: handleInputFocus, onClose: resetState },
             React.createElement(PiaConversation, { ...conversationHistoryProps })));
     }
     if (isConversation)
         return React.createElement(PiaConversation, { ...conversationHistoryProps });
-    const disclaimer = (React.createElement(Disclaimer, { learnMoreUrl: learnMoreUrl, translations: translations, componentOverride: componentOverrides?.disclaimer }));
     // Default inline mode
-    return (React.createElement("div", { className: 'cio-pia-container', "data-testid": 'cio-pia-container' },
+    return (React.createElement("div", { ref: containerRef, className: 'cio-pia-container', "data-testid": 'cio-pia-container' },
         React.createElement(RenderPropsWrapper, { props: renderProps, override: children || componentOverrides?.reactNode },
             React.createElement("p", { className: 'cio-pia-title', "data-testid": 'cio-pia-title' }, translate('Any questions about this product?', translations)),
-            React.createElement(Input, { onSubmit: handleSubmitQuestion, value: currentQuestion, translations: translations }),
+            React.createElement(Input, { onSubmit: handleSubmitQuestion, onFocus: handleInputFocus, value: currentQuestion, translations: translations }),
             isLoading && React.createElement(LoadingSkeleton, null),
             !isLoading && error && React.createElement(ErrorBlock, { message: error?.message || 'Unexpected error' }),
             !isLoading && !error && (React.createElement(React.Fragment, null,
-                currentAnswer && (React.createElement("div", { className: 'cio-pia-answer-container' },
-                    disclaimerPosition === 'top' && disclaimer,
-                    React.createElement(Answer, { text: currentAnswer, componentOverride: componentOverrides?.answer }),
-                    currentItems && (React.createElement(PiaCustomCarousel, { items: currentItems, componentOverrides: componentOverrides?.carousel, callbacks: callbacks })),
-                    showFeedback && (React.createElement(Feedback, { translations: translations, onFeedback: callbacks?.onFeedback, componentOverride: componentOverrides?.feedback })),
-                    disclaimerPosition === 'bottom' && disclaimer)),
-                React.createElement(SuggestedQuestionsContainer, { questions: displayedQuestions, onQuestionClick: handleSubmitQuestion, componentOverride: componentOverrides?.suggestedQuestions }))))));
+                currentAnswer && (React.createElement(PiaInlineAnswer, { currentAnswer: currentAnswer, currentItems: currentItems, showFeedback: showFeedback, learnMoreUrl: learnMoreUrl, disclaimerPosition: disclaimerPosition, translations: translations, callbacks: callbacks, componentOverrides: componentOverrides })),
+                React.createElement(SuggestedQuestionsContainer, { questions: displayedQuestions, onQuestionClick: handleQuestionClick, componentOverride: componentOverrides?.suggestedQuestions }))))));
 }

package/lib/mjs/components/CioPia/PiaCustomCarousel.js

@@ -1,5 +1,12 @@
-import React, { useCallback, useRef, useEffect } from 'react';
+import React, { useCallback, useRef, useEffect, useMemo } from 'react';
 import { Carousel, CIO_EVENTS, } from '@constructor-io/constructorio-ui-components';
+import { sanitizeHtml } from '../../utils/contentTransformers';
+function HtmlDescription({ product }) {
+    const { description } = product;
+    if (!description)
+        return null;
+    return (React.createElement("p", { className: 'cio-product-card-description', dangerouslySetInnerHTML: { __html: sanitizeHtml(description) } }));
+}
 export default function PiaCustomCarousel({ items, componentOverrides, callbacks, }) {
     const wrapperRef = useRef(null);
     // Determine to use user-defined click handler or default behavior
@@ -28,10 +35,28 @@ export default function PiaCustomCarousel({ items, componentOverrides, callbacks
             el.removeEventListener(CIO_EVENTS.productCard.click, handleClick);
         };
     }, [productClickHandler]);
+    const mergedOverrides = useMemo(() => {
+        if (componentOverrides?.item?.productCard?.content?.description) {
+            return componentOverrides;
+        }
+        return {
+            ...componentOverrides,
+            item: {
+                ...componentOverrides?.item,
+                productCard: {
+                    ...componentOverrides?.item?.productCard,
+                    content: {
+                        ...componentOverrides?.item?.productCard?.content,
+                        description: { reactNode: HtmlDescription },
+                    },
+                },
+            },
+        };
+    }, [componentOverrides]);
     // If there are no items, do not render the carousel
     if (items.length === 0) {
         return null;
     }
     return (React.createElement("div", { ref: wrapperRef },
-        React.createElement(Carousel, { items: items, componentOverrides: componentOverrides })));
+        React.createElement(Carousel, { items: items, componentOverrides: mergedOverrides })));
 }

package/lib/mjs/components/Input/Input.js

@@ -5,7 +5,7 @@ function SendIcon() {
         React.createElement("g", { id: '.icon-send' },
             React.createElement("path", { id: 'Vector', d: 'M14.8934 7.09533L14.8884 7.09314L1.54219 1.55752C1.42993 1.51053 1.30778 1.49211 1.18666 1.50388C1.06554 1.51566 0.949225 1.55728 0.848125 1.62502C0.741311 1.69501 0.653573 1.79045 0.592805 1.90277C0.532037 2.01509 0.500145 2.14075 0.5 2.26845V5.80877C0.50006 5.98335 0.561019 6.15243 0.67237 6.28689C0.783722 6.42134 0.938491 6.51274 1.11 6.54533L8.38906 7.89127C8.41767 7.89669 8.44348 7.91193 8.46205 7.93435C8.48062 7.95677 8.49078 7.98497 8.49078 8.01408C8.49078 8.04319 8.48062 8.07139 8.46205 8.09381C8.44348 8.11623 8.41767 8.13147 8.38906 8.13689L1.11031 9.48283C0.938851 9.51533 0.784092 9.60661 0.67269 9.74094C0.561288 9.87528 0.500219 10.0443 0.5 10.2188V13.7597C0.499917 13.8816 0.530111 14.0017 0.587871 14.1091C0.645632 14.2165 0.729152 14.3079 0.830938 14.375C0.953375 14.4564 1.09706 14.4998 1.24406 14.5C1.34626 14.4999 1.4474 14.4794 1.54156 14.4397L14.8875 8.93564L14.8934 8.93283C15.0731 8.85563 15.2262 8.72745 15.3337 8.56415C15.4413 8.40086 15.4986 8.20961 15.4986 8.01408C15.4986 7.81855 15.4413 7.6273 15.3337 7.46401C15.2262 7.30071 15.0731 7.17253 14.8934 7.09533Z', fill: 'white' }))));
 }
-function Input({ value: providedValue, placeholder, disabled = false, onSubmit, translations, }) {
+function Input({ value: providedValue, placeholder, disabled = false, onSubmit, onFocus, translations, }) {
     const [value, setValue] = useState(providedValue || '');
     useEffect(() => {
         if (providedValue) {
@@ -29,7 +29,7 @@ function Input({ value: providedValue, placeholder, disabled = false, onSubmit,
         ? translate('Ask anything', translations)
         : (placeholder ?? translate('Ask anything'));
     return (React.createElement("div", { className: 'cio-pia-input-container' },
-        React.createElement("input", { type: 'text', value: value, onChange: (e) => setValue(e.target.value), onKeyDown: handleSubmitOnEnter, placeholder: resolvedPlaceholder, disabled: disabled, className: 'cio-pia-input' }),
+        React.createElement("input", { type: 'text', value: value, onChange: (e) => setValue(e.target.value), onKeyDown: handleSubmitOnEnter, onFocus: onFocus, placeholder: resolvedPlaceholder, disabled: disabled, className: 'cio-pia-input' }),
         React.createElement("button", { type: 'button', onClick: handleSubmit, className: 'cio-pia-send-button', disabled: disabled },
             translate('Send', translations),
             React.createElement(SendIcon, null))));

package/lib/mjs/components/PiaConversation/PiaConversation.js

@@ -4,13 +4,13 @@ import SuggestedQuestionsContainer from '../SuggestedQuestionsContainer/Suggeste
 import SuggestedQuestionsSkeleton from '../SuggestedQuestionsContainer/SuggestedQuestionsSkeleton';
 import { translate } from '../../utils/translate';
 import ConversationHistory from '../ConversationHistory/ConversationHistory';
-export default function PiaConversation({ conversationHistory, isLoading, error, currentItems, showFeedback, showPreviousItems, learnMoreUrl, disclaimerPosition, translations, callbacks, componentOverrides, displayedQuestions, handleSubmitQuestion, }) {
+export default function PiaConversation({ conversationHistory, isLoading, error, currentItems, showFeedback, showPreviousItems, learnMoreUrl, disclaimerPosition, translations, callbacks, componentOverrides, displayedQuestions, handleSubmitQuestion, handleQuestionClick, containerRef, onInputFocus, }) {
     const hasHistory = conversationHistory.length > 0;
-    return (React.createElement("div", { className: 'cio-pia-container cio-pia-conversation', "data-testid": 'cio-pia-container' },
+    return (React.createElement("div", { ref: containerRef, className: 'cio-pia-container cio-pia-conversation', "data-testid": 'cio-pia-container' },
         !hasHistory && (React.createElement("p", { className: 'cio-pia-title', "data-testid": 'cio-pia-title' }, translate('Any questions about this product?', translations))),
         React.createElement(ConversationHistory, { conversationHistory: conversationHistory, isLoading: isLoading, error: error, currentItems: currentItems, showFeedback: showFeedback, showPreviousItems: showPreviousItems, learnMoreUrl: learnMoreUrl, disclaimerPosition: disclaimerPosition, translations: translations, callbacks: callbacks, componentOverrides: componentOverrides }),
         React.createElement("div", { className: 'cio-pia-conversation-footer' },
             isLoading && !error && React.createElement(SuggestedQuestionsSkeleton, null),
-            !isLoading && !error && (React.createElement(SuggestedQuestionsContainer, { questions: displayedQuestions, onQuestionClick: handleSubmitQuestion, componentOverride: componentOverrides?.suggestedQuestions })),
-            React.createElement(Input, { onSubmit: handleSubmitQuestion, disabled: isLoading, translations: translations }))));
+            !isLoading && !error && (React.createElement(SuggestedQuestionsContainer, { questions: displayedQuestions, onQuestionClick: handleQuestionClick, componentOverride: componentOverrides?.suggestedQuestions })),
+            React.createElement(Input, { onSubmit: handleSubmitQuestion, onFocus: onInputFocus, disabled: isLoading, translations: translations }))));
 }

package/lib/mjs/components/PiaConversation/PiaModal.js

@@ -7,7 +7,7 @@ function CloseIcon() {
     return (React.createElement("svg", { width: '20', height: '20', viewBox: '0 0 20 20', fill: 'none', xmlns: 'http://www.w3.org/2000/svg' },
         React.createElement("path", { d: 'M15.8334 5.34166L14.6584 4.16666L10.0001 8.82499L5.34175 4.16666L4.16675 5.34166L8.82508 9.99999L4.16675 14.6583L5.34175 15.8333L10.0001 11.175L14.6584 15.8333L15.8334 14.6583L11.1751 9.99999L15.8334 5.34166Z', fill: 'currentColor' })));
 }
-export default function PiaModal({ initialQuestions, handleSubmitQuestion, isLoading, componentOverrides, translations, onClose, children, }) {
+export default function PiaModal({ initialQuestions, handleSubmitQuestion, handleQuestionClick, containerRef, isLoading, componentOverrides, translations, onInputFocus, onClose, children, }) {
     const [isOpen, setIsOpen] = useState(false);
     const dialogRef = useRef(null);
     const openModal = useCallback(() => {
@@ -56,11 +56,15 @@ export default function PiaModal({ initialQuestions, handleSubmitQuestion, isLoa
         handleSubmitQuestion(question);
         openModal();
     }, [handleSubmitQuestion, openModal]);
-    return (React.createElement("div", { className: 'cio-pia-container', "data-testid": 'cio-pia-container' },
+    const handleQuestionClicked = useCallback((question) => {
+        handleQuestionClick(question);
+        openModal();
+    }, [handleQuestionClick, openModal]);
+    return (React.createElement("div", { ref: containerRef, className: 'cio-pia-container', "data-testid": 'cio-pia-container' },
         React.createElement("p", { className: 'cio-pia-title', "data-testid": 'cio-pia-title' }, translate('Any questions about this product?', translations)),
         React.createElement("div", { className: 'cio-pia-conversation-footer' },
-            initialQuestions.length > 0 && (React.createElement(SuggestedQuestionsContainer, { questions: initialQuestions, onQuestionClick: handleQuestion, componentOverride: componentOverrides?.suggestedQuestions })),
-            React.createElement(Input, { onSubmit: handleQuestion, disabled: isLoading || isOpen, translations: translations })),
+            initialQuestions.length > 0 && (React.createElement(SuggestedQuestionsContainer, { questions: initialQuestions, onQuestionClick: handleQuestionClicked, componentOverride: componentOverrides?.suggestedQuestions })),
+            React.createElement(Input, { onSubmit: handleQuestion, onFocus: onInputFocus, disabled: isLoading || isOpen, translations: translations })),
         React.createElement("dialog", { ref: dialogRef, className: 'cio-pia-modal', "aria-labelledby": 'cio-pia-modal-title' },
             React.createElement("div", { className: 'cio-pia-modal-content' },
                 React.createElement("div", { className: 'cio-pia-modal-header' },

package/lib/mjs/components/PiaInlineAnswer/PiaInlineAnswer.js

@@ -0,0 +1,14 @@
+import React from 'react';
+import Answer from '../Answer/Answer';
+import Feedback from '../Feedback/Feedback';
+import Disclaimer from '../CioPia/Disclaimer';
+import PiaCustomCarousel from '../CioPia/PiaCustomCarousel';
+export default function PiaInlineAnswer({ currentAnswer, currentItems, showFeedback, learnMoreUrl, disclaimerPosition = 'bottom', translations, callbacks, componentOverrides, }) {
+    const disclaimer = (React.createElement(Disclaimer, { learnMoreUrl: learnMoreUrl, translations: translations, componentOverride: componentOverrides?.disclaimer }));
+    return (React.createElement("div", { className: 'cio-pia-answer-container' },
+        disclaimerPosition === 'top' && disclaimer,
+        React.createElement(Answer, { text: currentAnswer, componentOverride: componentOverrides?.answer }),
+        currentItems && (React.createElement(PiaCustomCarousel, { items: currentItems, componentOverrides: componentOverrides?.carousel, callbacks: callbacks })),
+        showFeedback && (React.createElement(Feedback, { translations: translations, onFeedback: callbacks?.onFeedback, componentOverride: componentOverrides?.feedback })),
+        disclaimerPosition === 'bottom' && disclaimer));
+}

package/lib/mjs/constants.js

@@ -1,4 +1,3 @@
-// eslint-disable-next-line import/prefer-default-export
 export const DEMO_API_KEY = 'key_13TO6qN9H3BP3Wrn';
 export const DEMO_ITEM_ID = '149100215';
 export const DEMO_QUESTION = 'What is the nutritional content of this shake?';

package/lib/mjs/hooks/useAnswerResults.js

@@ -1,4 +1,4 @@
-import { useCallback, useState } from 'react';
+import { useCallback, useMemo, useState } from 'react';
 import { transformResultItem } from '../utils/transformers';
 const extractAndTransformItems = (data, formatImageUrl) => {
     if (!data?.item_results?.response?.results) {
@@ -24,9 +24,9 @@ const fetchAnswerResults = async ({ client, itemId, question, variationId, threa
 };
 export default function useAnswerResults({ itemId, variationId, threadId, cioClient, formatImageUrl, }) {
     const [answerResults, setAnswerResults] = useState(null);
-    const [items, setItems] = useState(null);
     const [isLoading, setIsLoading] = useState(false);
     const [error, setError] = useState(null);
+    const items = useMemo(() => extractAndTransformItems(answerResults, formatImageUrl), [answerResults, formatImageUrl]);
     const fetchResult = useCallback((question) => {
         if (!cioClient)
             return;
@@ -35,18 +35,16 @@ export default function useAnswerResults({ itemId, variationId, threadId, cioCli
         fetchAnswerResults({ client: cioClient, itemId, question, variationId, threadId })
             .then((fetchedAnswerResults) => {
             setAnswerResults(fetchedAnswerResults);
-            setItems(extractAndTransformItems(fetchedAnswerResults, formatImageUrl));
             setError(null);
         })
             .catch((err) => {
             setError(err instanceof Error ? err : new Error('Error fetching answer'));
             setAnswerResults(null);
-            setItems(null);
         })
             .finally(() => {
             setIsLoading(false);
         });
-    }, [cioClient, itemId, variationId, threadId, formatImageUrl]);
+    }, [cioClient, itemId, variationId, threadId]);
     return {
         data: answerResults,
         items,

package/lib/mjs/hooks/useCioPia.js

@@ -1,8 +1,11 @@
+import { useState } from 'react';
 import useAnswerResults from './useAnswerResults';
 import useCioClient from './useCioClient';
 import useSuggestedQuestions from './useSuggestedQuestions';
 export default function useCioPia(props) {
-    const { apiKey, itemId, variationId, threadId, cioClient: providedClient, suggestedQuestionsParameters, formatImageUrl, } = props;
+    const { apiKey, itemId, variationId, threadId: providedThreadId, cioClient: providedClient, suggestedQuestionsParameters, formatImageUrl, } = props;
+    const [generatedThreadId] = useState(() => crypto.randomUUID());
+    const threadId = providedThreadId || generatedThreadId;
     const defaultClient = useCioClient({ apiKey });
     const client = providedClient || defaultClient;
     const suggestedQuestions = useSuggestedQuestions({
@@ -20,6 +23,7 @@ export default function useCioPia(props) {
         formatImageUrl,
     });
     return {
+        threadId,
         suggestedQuestions,
         answers,
     };

package/lib/mjs/hooks/useConversation.js

@@ -1,22 +1,45 @@
-import { useCallback, useEffect, useRef, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 export default function useConversation({ pia, itemId, isConversation, callbacks, }) {
-    const { suggestedQuestions, answers } = pia;
+    const { suggestedQuestions, answers, threadId } = pia;
     const { getAnswer } = answers;
+    const context = useMemo(() => ({ itemId, threadId }), [itemId, threadId]);
     const [currentQuestion, setCurrentQuestion] = useState('');
     const [displayedQuestions, setDisplayedQuestions] = useState([]);
     const [conversationHistory, setConversationHistory] = useState([]);
     const entryIdRef = useRef(0);
     const prevAnswerValueRef = useRef(answers.data?.value);
-    const handleSubmitQuestion = useCallback((question) => {
-        callbacks?.onQuestionSubmit?.(question);
+    const callbacksRef = useRef(callbacks);
+    const contextRef = useRef(context);
+    const lastQuestionRef = useRef('');
+    const lastSourceRef = useRef('user');
+    useEffect(() => {
+        callbacksRef.current = callbacks;
+    }, [callbacks]);
+    useEffect(() => {
+        contextRef.current = context;
+    }, [context]);
+    const submitQuestion = useCallback((question, source) => {
+        lastSourceRef.current = source;
+        lastQuestionRef.current = question;
         setCurrentQuestion(question);
         getAnswer(question);
         if (isConversation) {
             entryIdRef.current += 1;
             const id = entryIdRef.current;
-            setConversationHistory((prev) => [...prev, { id, question, answer: '' }]);
+            setConversationHistory((prev) => [...prev, { id, question, answer: '', source }]);
         }
-    }, [getAnswer, isConversation, callbacks]);
+    }, [getAnswer, isConversation]);
+    const handleSubmitQuestion = useCallback((question) => {
+        callbacksRef.current?.onQuestionSubmit?.(question, contextRef.current, 'user');
+        submitQuestion(question, 'user');
+    }, [submitQuestion]);
+    const handleQuestionClick = useCallback((question) => {
+        callbacksRef.current?.onQuestionSubmit?.(question, contextRef.current, 'suggestion');
+        submitQuestion(question, 'suggestion');
+    }, [submitQuestion]);
+    const handleInputFocus = useCallback(() => {
+        callbacksRef.current?.onFocus?.(contextRef.current);
+    }, []);
     const resetState = useCallback(() => {
         setCurrentQuestion('');
         setDisplayedQuestions(suggestedQuestions.data);
@@ -38,22 +61,41 @@ export default function useConversation({ pia, itemId, isConversation, callbacks
     }, [answers.data]);
     useEffect(() => {
         const answerValue = answers.data?.value ?? '';
-        if (!isConversation || !answerValue)
+        if (!answerValue)
             return;
         if (answerValue === prevAnswerValueRef.current)
             return;
         prevAnswerValueRef.current = answerValue;
-        setConversationHistory((prev) => {
-            if (prev.length === 0)
-                return prev;
-            const updated = [...prev];
-            updated[updated.length - 1] = {
-                ...updated[updated.length - 1],
+        const answerThreadId = answers.data?.thread_id;
+        const qnaResultId = answers.data?.qna_result_id;
+        if (isConversation) {
+            setConversationHistory((prev) => {
+                if (prev.length === 0)
+                    return prev;
+                const updated = [...prev];
+                updated[updated.length - 1] = {
+                    ...updated[updated.length - 1],
+                    answer: answerValue,
+                    items: answers.items,
+                    threadId: answerThreadId,
+                    qnaResultId,
+                };
+                callbacksRef.current?.onAnswer?.(updated, contextRef.current);
+                return updated;
+            });
+        }
+        else {
+            const entry = {
+                id: entryIdRef.current,
+                question: lastQuestionRef.current,
                 answer: answerValue,
+                source: lastSourceRef.current,
                 items: answers.items,
+                threadId: answerThreadId,
+                qnaResultId,
             };
-            return updated;
-        });
+            callbacksRef.current?.onAnswer?.([entry], contextRef.current);
+        }
     }, [isConversation, answers.data, answers.items]);
     const currentAnswer = answers.data?.value ?? '';
     const currentItems = answers.items ?? null;
@@ -67,7 +109,10 @@ export default function useConversation({ pia, itemId, isConversation, callbacks
         currentItems,
         isLoading,
         error,
+        context,
         handleSubmitQuestion,
+        handleQuestionClick,
+        handleInputFocus,
         resetState,
     };
 }

package/lib/mjs/hooks/useViewportCallbacks.js

@@ -0,0 +1,45 @@
+import { useCallback, useEffect, useRef } from 'react';
+export default function useViewportCallbacks({ callbacks, context, }) {
+    const callbacksRef = useRef(callbacks);
+    const contextRef = useRef(context);
+    const hasBeenVisibleRef = useRef(false);
+    const hasFiredOutOfViewRef = useRef(false);
+    const observerRef = useRef(null);
+    useEffect(() => {
+        callbacksRef.current = callbacks;
+    }, [callbacks]);
+    useEffect(() => {
+        contextRef.current = context;
+    }, [context]);
+    useEffect(() => {
+        return () => {
+            observerRef.current?.disconnect();
+        };
+    }, []);
+    const containerRef = useCallback((node) => {
+        if (observerRef.current) {
+            observerRef.current.disconnect();
+            observerRef.current = null;
+        }
+        if (!node)
+            return;
+        hasBeenVisibleRef.current = false;
+        hasFiredOutOfViewRef.current = false;
+        const observer = new IntersectionObserver(([entry]) => {
+            if (entry.isIntersecting && !hasBeenVisibleRef.current) {
+                hasBeenVisibleRef.current = true;
+                callbacksRef.current?.onView?.(contextRef.current);
+            }
+            else if (!entry.isIntersecting &&
+                hasBeenVisibleRef.current &&
+                !hasFiredOutOfViewRef.current) {
+                hasFiredOutOfViewRef.current = true;
+                callbacksRef.current?.onOutOfView?.(contextRef.current);
+                observer.disconnect();
+            }
+        }, { threshold: 0.5 });
+        observer.observe(node);
+        observerRef.current = observer;
+    }, []);
+    return { containerRef };
+}

package/lib/mjs/index.js

@@ -1,6 +1,8 @@
 import CioPia from './components/CioPia';
 // Components
 export { default as CioPia } from './components/CioPia';
+// Utilities
+export { sanitizeHtml, renderMarkdown } from './utils/contentTransformers';
 // Default
 export * from './types';
 export default CioPia;

package/lib/mjs/stories/assets/storybook-styles.css

@@ -110,3 +110,92 @@ div.badge-wrapper code {
   background: #d8e8fd;
   color: #3c70bf;
 }
+
+.cio-flow-diagram {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  margin: 24px 0 0;
+  font-family: system-ui, sans-serif;
+  font-size: 14px;
+}
+
+.cio-flow-diagram .flow-step {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+}
+
+.cio-flow-diagram .flow-box {
+  padding: 10px 16px;
+  border-radius: 8px;
+  min-width: 220px;
+  text-align: center;
+}
+
+.cio-flow-diagram .flow-box--consumer {
+  background: #eff6ff;
+  border: 1px solid #bfdbfe;
+}
+
+.cio-flow-diagram .flow-box--internal {
+  background: #f5f3ff;
+  border: 1px solid #ddd6fe;
+}
+
+.cio-flow-diagram .flow-box--output {
+  background: #f0fdf4;
+  border: 1px solid #bbf7d0;
+}
+
+.cio-flow-diagram .flow-arrow {
+  margin-left: 110px;
+  color: #9ca3af;
+}
+
+.cio-flow-diagram .flow-label {
+  font-size: 12px;
+  color: #9ca3af;
+  font-style: italic;
+}
+
+.cio-flow-diagram .flow-callback {
+  font-size: 12px;
+  color: #059669;
+}
+
+.cio-flow-diagram .flow-box-subtitle {
+  font-size: 12px;
+  color: #6b7280;
+}
+
+.cio-flow-legend {
+  display: flex;
+  gap: 16px;
+  margin: 32px 0 16px;
+  font-size: 12px;
+}
+
+.cio-flow-legend .legend-swatch {
+  display: inline-block;
+  width: 12px;
+  height: 12px;
+  border-radius: 3px;
+  margin-right: 4px;
+  vertical-align: middle;
+}
+
+.cio-flow-legend .legend-swatch--consumer {
+  background: #eff6ff;
+  border: 1px solid #bfdbfe;
+}
+
+.cio-flow-legend .legend-swatch--internal {
+  background: #f5f3ff;
+  border: 1px solid #ddd6fe;
+}
+
+.cio-flow-legend .legend-swatch--output {
+  background: #f0fdf4;
+  border: 1px solid #bbf7d0;
+}

package/lib/mjs/utils/contentTransformers.js

@@ -0,0 +1,16 @@
+import DOMPurify from 'dompurify';
+import { marked } from 'marked';
+const purifyConfig = {
+    FORBID_TAGS: ['script', 'style', 'iframe', 'object', 'embed', 'form'],
+};
+export function sanitizeHtml(html) {
+    if (!html)
+        return '';
+    return DOMPurify.sanitize(html, purifyConfig);
+}
+export function renderMarkdown(content) {
+    if (!content)
+        return '';
+    const html = marked.parse(content, { async: false, breaks: true });
+    return DOMPurify.sanitize(html, purifyConfig);
+}

package/lib/mjs/utils/index.js

@@ -1 +1,2 @@
 export * from './styleHelpers';
+export { sanitizeHtml, renderMarkdown } from './contentTransformers';

package/lib/mjs/utils/styleHelpers.js

@@ -1,4 +1,3 @@
-// eslint-disable-next-line import/prefer-default-export
 export function getPreferredColorScheme() {
     let colorScheme = 'light';
     // Check if the dark-mode Media-Query matches

package/lib/mjs/utils/translate.js

@@ -16,7 +16,6 @@ const defaultTranslations = {
  * @param translations - Optional user-provided translations object
  * @returns The translated string or the original word if no translation exists
  */
-// eslint-disable-next-line import/prefer-default-export
 export const translate = (word, translations) => {
     if (translations && translations[word] !== undefined) {
         return translations[word];

package/lib/mjs/version.js

@@ -1 +1 @@
-export default '2.3.0';
+export default '2.6.2';

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

@@ -3,29 +3,27 @@ import { IncludeComponentOverrides, IncludeRenderProps } from '@constructor-io/c
 import MockConstructorIOClient from '../../hooks/mocks/MockConstructorIOClient';
 import { CioPiaRenderProps, CioPiaComponentOverrides, Callbacks, CioPiaDisplayConfigs, Translations, SuggestedQuestionsParameters, Formatters } from '../../types';
 export interface CioPiaProps extends IncludeRenderProps<CioPiaRenderProps>, IncludeComponentOverrides<CioPiaComponentOverrides> {
+    /** Your Constructor.io API key. */
     apiKey: string;
+    /** The product item ID to fetch insights for. */
     itemId: string;
-    /** Thread ID for conversation context. Must be a valid UUID (e.g., "550e8400-e29b-41d4-a716-446655440000") */
+    /** Thread ID for conversation context. Must be a valid UUID (e.g., "550e8400-e29b-41d4-a716-446655440000"). */
     threadId?: string;
+    /** Optional variation ID for the product. */
     variationId?: string;
+    /** Optional Constructor.io client instance. If not provided, one will be created internally. */
     cioClient?: MockConstructorIOClient;
+    /** Display configuration options (mode, type, showFeedback, etc.). */
     displayConfigs?: CioPiaDisplayConfigs;
-    /**
-     * Callback handlers for user interactions:
-     *
-     * `onQuestionSubmit: (question: string) => void`
-     * Called when a question is submitted (via Enter key, Send button, or suggested question click).
-     *
-     * `onProductCardClick: (item: Item) => void`
-     * Called when a product card in the carousel is clicked.
-     *
-     * `onFeedback: (type: 'up' | 'down') => void`
-     * Called when the user submits positive or negative feedback on an answer.
-     */
+    /** Callback handlers for user interactions (onQuestionSubmit, onProductCardClick, onFeedback). */
     callbacks?: Callbacks;
-    /** Define formatter functions outside the component or memoize to avoid unnecessary re-renders. */
+    /** Custom component overrides via reactNode or render props functions. */
+    componentOverrides?: CioPiaComponentOverrides;
+    /** Formatter functions for transforming data before display. */
     formatters?: Formatters;
+    /** UI string translations for internationalization. */
     translations?: Translations;
+    /** Parameters for the suggested questions request. */
     suggestedQuestionsParameters?: SuggestedQuestionsParameters;
 }
 export default function CioPia(props: CioPiaProps): React.JSX.Element;

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

@@ -6,7 +6,8 @@ interface InputProps {
     /** @deprecated Use the `translations` prop instead. */
     placeholder?: string;
     onSubmit: (value: string) => void;
+    onFocus?: () => void;
     translations?: Translations;
 }
-declare function Input({ value: providedValue, placeholder, disabled, onSubmit, translations, }: InputProps): React.JSX.Element;
+declare function Input({ value: providedValue, placeholder, disabled, onSubmit, onFocus, translations, }: InputProps): React.JSX.Element;
 export default Input;

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

@@ -4,5 +4,8 @@ import { ConversationHistoryProps } from '../ConversationHistory/ConversationHis
 export interface PiaConversationProps extends ConversationHistoryProps {
     displayedQuestions: Question[];
     handleSubmitQuestion: (question: string) => void;
+    handleQuestionClick: (question: string) => void;
+    containerRef?: (node: HTMLDivElement | null) => void;
+    onInputFocus?: () => void;
 }
-export default function PiaConversation({ conversationHistory, isLoading, error, currentItems, showFeedback, showPreviousItems, learnMoreUrl, disclaimerPosition, translations, callbacks, componentOverrides, displayedQuestions, handleSubmitQuestion, }: PiaConversationProps): React.JSX.Element;
+export default function PiaConversation({ conversationHistory, isLoading, error, currentItems, showFeedback, showPreviousItems, learnMoreUrl, disclaimerPosition, translations, callbacks, componentOverrides, displayedQuestions, handleSubmitQuestion, handleQuestionClick, containerRef, onInputFocus, }: PiaConversationProps): React.JSX.Element;