@constructor-io/constructorio-ui-pia 2.4.0 → 2.6.3

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/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

@@ -8,9 +8,14 @@ export function sanitizeHtml(html) {
         return '';
     return DOMPurify.sanitize(html, purifyConfig);
 }
-export function renderMarkdown(content) {
+export function renderMarkdown(content, options) {
     if (!content)
         return '';
-    const html = marked.parse(content, { async: false });
+    const html = marked.parse(content, { async: false, breaks: true });
+    if (options?.sanitize) {
+        const purifier = DOMPurify(window);
+        const config = { ...purifyConfig, FORBID_TAGS: [...(purifyConfig.FORBID_TAGS ?? [])] };
+        return options.sanitize(purifier, html, { config });
+    }
     return DOMPurify.sanitize(html, purifyConfig);
 }

package/lib/mjs/version.js

@@ -1 +1 @@
-export default '2.4.0';
+export default '2.6.3';

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;

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

@@ -3,10 +3,13 @@ import { Translations, Question, CioPiaComponentOverrides } from '../../types';
 interface PiaModalProps {
     initialQuestions: Question[];
     handleSubmitQuestion: (question: string) => void;
+    handleQuestionClick: (question: string) => void;
+    containerRef?: (node: HTMLDivElement | null) => void;
     isLoading: boolean;
     componentOverrides?: CioPiaComponentOverrides;
     translations?: Translations;
+    onInputFocus?: () => void;
     onClose?: () => void;
 }
-export default function PiaModal({ initialQuestions, handleSubmitQuestion, isLoading, componentOverrides, translations, onClose, children, }: PropsWithChildren<PiaModalProps>): React.JSX.Element;
+export default function PiaModal({ initialQuestions, handleSubmitQuestion, handleQuestionClick, containerRef, isLoading, componentOverrides, translations, onInputFocus, onClose, children, }: PropsWithChildren<PiaModalProps>): React.JSX.Element;
 export {};

package/lib/types/hooks/mocks/MockConstructorIOClient.d.ts

@@ -2,7 +2,7 @@ import { ConstructorClientOptions } from '@constructor-io/constructorio-client-j
 import { Recommendations, Browse, Search, Tracker, Quizzes } from '@constructor-io/constructorio-client-javascript/lib/types/constructorio';
 import MockAgent from './agent';
 declare class MockConstructorIOClient {
-    private options;
+    options: ConstructorClientOptions;
     search: Search;
     browse: Browse;
     recommendations: Recommendations;

package/lib/types/hooks/useCioPia.d.ts

@@ -13,6 +13,7 @@ export interface UseCioPiaProps {
     formatImageUrl?: Formatters['formatImageUrl'];
 }
 export interface UseCioPiaReturn {
+    threadId: string;
     suggestedQuestions: UseSuggestedQuestionsReturn;
     answers: UseAnswerResultsReturn;
 }

package/lib/types/hooks/useConversation.d.ts

@@ -1,4 +1,4 @@
-import { Callbacks, ConversationEntry, Question, Item } from '../types';
+import { Callbacks, ConversationEntry, PiaCallbackContext, Question, Item } from '../types';
 import { UseCioPiaReturn } from './useCioPia';
 export interface UseConversationProps {
     pia: UseCioPiaReturn;
@@ -14,7 +14,10 @@ export interface UseConversationReturn {
     currentItems: Item[] | null;
     isLoading: boolean;
     error: Error | null;
+    context: PiaCallbackContext;
     handleSubmitQuestion: (question: string) => void;
+    handleQuestionClick: (question: string) => void;
+    handleInputFocus: () => void;
     resetState: () => void;
 }
 export default function useConversation({ pia, itemId, isConversation, callbacks, }: UseConversationProps): UseConversationReturn;

package/lib/types/hooks/useViewportCallbacks.d.ts

@@ -0,0 +1,9 @@
+import { Callbacks, PiaCallbackContext } from '../types';
+export interface UseViewportCallbacksProps {
+    callbacks?: Callbacks;
+    context: PiaCallbackContext;
+}
+export interface UseViewportCallbacksReturn {
+    containerRef: (node: HTMLDivElement | null) => void;
+}
+export default function useViewportCallbacks({ callbacks, context, }: UseViewportCallbacksProps): UseViewportCallbacksReturn;

package/lib/types/index.d.ts

@@ -2,5 +2,6 @@ import CioPia from './components/CioPia';
 export { default as CioPia } from './components/CioPia';
 export type { CioPiaProps } from './components/CioPia';
 export { sanitizeHtml, renderMarkdown } from './utils/contentTransformers';
+export type { RenderMarkdownOptions, SanitizeOptions } from './utils/contentTransformers';
 export * from './types';
 export default CioPia;

package/lib/types/types.d.ts

@@ -60,13 +60,26 @@ export type Translations = {
     'Learn More.'?: string;
     'Ask about this product'?: string;
 };
+export type QuestionSource = 'user' | 'suggestion';
+export interface PiaCallbackContext {
+    itemId: string;
+    threadId: string;
+}
 export interface Callbacks {
-    /** Called when a question is submitted (via Enter key, Send button, or suggested question click). */
-    onQuestionSubmit?: (question: string) => void;
+    /** Called when a question is submitted (typed or suggested question clicked). */
+    onQuestionSubmit?: (question: string, context: PiaCallbackContext, source: QuestionSource) => void;
     /** Called when a product card in the carousel is clicked. */
     onProductCardClick?: (item: Item) => void;
     /** Called when the user submits positive or negative feedback on an answer. */
     onFeedback?: (type: FeedbackType) => void;
+    /** Called when a new answer is received. Passes the full conversation history. */
+    onAnswer?: (history: ConversationEntry[], context: PiaCallbackContext) => void;
+    /** Called when the user focuses the input field. */
+    onFocus?: (context: PiaCallbackContext) => void;
+    /** Called when the widget enters the viewport. */
+    onView?: (context: PiaCallbackContext) => void;
+    /** Called when the widget leaves the viewport. */
+    onOutOfView?: (context: PiaCallbackContext) => void;
 }
 /** Formatter functions for transforming data before display. */
 export interface Formatters {
@@ -82,7 +95,10 @@ export interface ConversationEntry {
     id: number;
     question: string;
     answer: string;
+    source: QuestionSource;
     items?: Item[] | null;
+    threadId?: string;
+    qnaResultId?: string;
 }
 /**
  * Render props passed to CioPia children function

package/lib/types/utils/contentTransformers.d.ts

@@ -1,2 +1,27 @@
+import DOMPurify from 'dompurify';
+export interface SanitizeOptions {
+    config: DOMPurify.Config;
+}
+/** Options for {@link renderMarkdown}. */
+export interface RenderMarkdownOptions {
+    /**
+     * Override the default DOMPurify sanitization step.
+     * Called with an isolated DOMPurify instance, the parsed HTML string,
+     * and an options object containing the default config. Must return the sanitized HTML string.
+     *
+     * @example
+     * sanitize: (purifier, html, { config }) => {
+     *   purifier.addHook('uponSanitizeAttribute', (node, event) => {
+     *     if (node.tagName === 'A' && event.attrName === 'href') {
+     *       if (/^javascript:window\.openChat\(\)$/.test(event.attrValue)) {
+     *         event.forceKeepAttr = true;
+     *       }
+     *     }
+     *   });
+     *   return purifier.sanitize(html, config);
+     * }
+     */
+    sanitize?: (purifier: typeof DOMPurify, html: string, options: SanitizeOptions) => string;
+}
 export declare function sanitizeHtml(html: string): string;
-export declare function renderMarkdown(content: string): string;
+export declare function renderMarkdown(content: string, options?: RenderMarkdownOptions): string;

package/lib/types/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "2.4.0";
+declare const _default: "2.6.3";
 export default _default;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructor-io/constructorio-ui-pia",
-  "version": "2.4.0",
+  "version": "2.6.3",
   "description": "Constructor.io AI Product Insights Agent UI library for web applications",
   "author": "Constructor.io Corporation",
   "license": "MIT",