@constructor-io/constructorio-ui-pia 2.10.4 → 2.12.0

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

@@ -1,9 +1,24 @@
 import React, { useCallback, useEffect, useState } from 'react';
 import { RenderPropsWrapper, } from '@constructor-io/constructorio-ui-components';
+import { cx } from '../../utils/classNames';
 import { translate } from '../../utils/translate';
 import { SendIcon } from '../icons';
-function Input({ value: providedValue, placeholder, disabled = false, onSubmit, onFocus, translations, componentOverride, }) {
+/**
+ * Numbers the `Input`s mounted on the page, so each one can give its error message a DOM `id` no
+ * other input will collide with. Nothing to do with messages or errors themselves - the id is
+ * needed because that is what the field's `aria-describedby` has to point at.
+ *
+ * `useId` is the built-in way to do this, but it is React 18+ and this package supports React
+ * >= 16.12. Read once per instance through a lazy initializer, so the number an input gets holds
+ * across its re-renders.
+ */
+let inputIdCounter = 0;
+function Input({ value: providedValue, placeholder, disabled = false, onSubmit, onFocus, translations, componentOverride, error, placeholderKey = 'Ask anything', showSendButton = true, }) {
     const [value, setValue] = useState(providedValue || '');
+    const [errorId] = useState(() => {
+        inputIdCounter += 1;
+        return `cio-pia-input-${inputIdCounter}-error`;
+    });
     useEffect(() => {
         if (providedValue) {
             setValue(providedValue);
@@ -24,20 +39,23 @@ function Input({ value: providedValue, placeholder, disabled = false, onSubmit,
         }
     };
     // Priority: translations > placeholder prop > default
-    const resolvedPlaceholder = translations?.['Ask anything'] !== undefined
-        ? translate('Ask anything', translations)
-        : (placeholder ?? translate('Ask anything'));
+    const resolvedPlaceholder = translations?.[placeholderKey] !== undefined
+        ? translate(placeholderKey, translations)
+        : (placeholder ?? translate(placeholderKey));
     return (React.createElement(RenderPropsWrapper, { props: {
             disabled,
             placeholder: resolvedPlaceholder,
             onSubmit: handleSubmit,
             onFocus,
             translations,
+            error,
         }, override: componentOverride?.reactNode },
-        React.createElement("div", { className: 'cio-pia-input-container' },
-            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(value), className: 'cio-pia-send-button', disabled: disabled },
-                translate('Send', translations),
-                React.createElement(SendIcon, null)))));
+        React.createElement(React.Fragment, null,
+            React.createElement("div", { className: 'cio-pia-input-container' },
+                React.createElement("input", { type: 'text', value: value, onChange: (e) => setValue(e.target.value), onKeyDown: handleSubmitOnEnter, onFocus: onFocus, placeholder: resolvedPlaceholder, disabled: disabled, className: cx('cio-pia-input', error && 'cio-pia-input--error', !showSendButton && 'cio-pia-input--no-send'), "aria-invalid": error ? true : undefined, "aria-describedby": error ? errorId : undefined }),
+                showSendButton && (React.createElement("button", { type: 'button', onClick: () => handleSubmit(value), className: 'cio-pia-send-button', disabled: disabled },
+                    translate('Send', translations),
+                    React.createElement(SendIcon, null)))),
+            error && (React.createElement("span", { className: 'cio-pia-input-error', id: errorId, role: 'alert' }, error)))));
 }
 export default Input;

package/lib/mjs/components/Input/InputStyles.css

@@ -21,11 +21,38 @@
     1px 1px 1px 0px rgba(18, 18, 105, 0.05) inset;
 }
 
+/*
+ * Input Without A Send Button
+ *
+ * The right padding above is room for the Send button. With no button there is nothing to keep
+ * clear of, and leaving it would truncate what the shopper typed well short of the border.
+ */
+.cio-pia-input--no-send {
+  padding-right: 12px;
+}
+
 /* Input Hover */
 .cio-pia-input:hover {
   border: 1px solid #c8cad0;
 }
 
+/* Input Rejected Value */
+.cio-pia-input--error,
+.cio-pia-input--error:hover,
+.cio-pia-input--error:focus {
+  border: 1px solid #d93025;
+  box-shadow: none;
+}
+
+/* Input Rejected Value Message */
+.cio-pia-input-error {
+  display: block;
+  margin-top: 4px;
+  color: #d93025;
+  font-size: 12px;
+  line-height: 16px;
+}
+
 /* Input Focus */
 .cio-pia-input:focus {
   outline: none;

package/lib/mjs/components/SuggestedQuestion/SuggestedQuestion.js

@@ -1,9 +1,8 @@
 import React from 'react';
 import { QuestionIcon } from '../icons';
-function SuggestedQuestion({ question, onClick }) {
+function SuggestedQuestion({ question, onClick, icon }) {
     return (React.createElement("button", { type: 'button', className: 'cio-pia-suggested-question', onClick: onClick },
-        React.createElement("div", { className: 'cio-pia-suggested-question-icon' },
-            React.createElement(QuestionIcon, null)),
+        React.createElement("div", { className: 'cio-pia-suggested-question-icon' }, icon ?? React.createElement(QuestionIcon, null)),
         question));
 }
 export default SuggestedQuestion;

package/lib/mjs/components/SuggestedQuestionsContainer/SuggestedQuestionsContainerStyles.css

@@ -21,7 +21,7 @@
 }
 
 .cio-pia-suggested-question-skeleton {
-  height: 28px;
+  height: 34px;
   border-radius: 4px;
   background-color: rgba(0, 0, 0, 0.05);
   animation: loading-animation 2s infinite ease-in-out;

package/lib/mjs/constants.js

@@ -12,3 +12,14 @@ export const MOCK_QUESTIONS = [
     { value: 'What is the serving size and calorie count?' },
 ];
 export const DISCLAIMER_TEXT = 'AI-generated answers aim to help, but they may occasionally miss details or be inaccurate. Double-check important information before purchasing.';
+/**
+ * Recommendations pod strings the API cannot supply, because in these states there is either
+ * no response yet or no usable response at all. Everything else the pod shows comes from the
+ * API. All five are `Translations` keys, so reference the constants instead of retyping the
+ * literals - a mistyped key falls back to itself with no warning.
+ */
+export const RECS_LOADING_TITLE = 'Adapting recommendations to your preference';
+export const RECS_FALLBACK_TITLE = 'Best selling products';
+export const RECS_UNSUPPORTED_REQUEST = 'Unsupported request, try a different feature.';
+export const RECS_REFINEMENT_LABEL = "Not what you're looking for? Try:";
+export const RECS_INPUT_PLACEHOLDER = 'Describe something else...';

package/lib/mjs/hooks/useAnswerResults.js

@@ -1,15 +1,5 @@
 import { useCallback, useMemo, useState } from 'react';
 import { extractAndTransformItems } from '../utils/transformers';
-const fetchAnswerResults = async ({ client, itemId, question, variationId, threadId, parameters, }) => {
-    const response = await client.agent.getAnswerResults({
-        itemId,
-        variationId,
-        threadId,
-        question,
-        parameters,
-    });
-    return response;
-};
 export default function useAnswerResults({ itemId, variationId, threadId, cioClient, parameters, formatImageUrl, }) {
     const [answerResults, setAnswerResults] = useState(null);
     const [isLoading, setIsLoading] = useState(false);
@@ -21,9 +11,10 @@ export default function useAnswerResults({ itemId, variationId, threadId, cioCli
         setIsLoading(true);
         setError(null);
         setAnswerResults(null);
-        fetchAnswerResults({ client: cioClient, itemId, question, variationId, threadId, parameters })
-            .then((fetchedAnswerResults) => {
-            setAnswerResults(fetchedAnswerResults);
+        cioClient.agent.pia
+            .getAnswerResults(itemId, question, { threadId, variationId, ...parameters })
+            .then((response) => {
+            setAnswerResults(response);
             setError(null);
         })
             .catch((err) => {

package/lib/mjs/hooks/useCioPia.js

@@ -1,35 +1,66 @@
-import { useMemo, useState } from 'react';
-import MockConstructorIOClient from './mocks/MockConstructorIOClient';
 import useAnswerResults from './useAnswerResults';
+import usePiaClient from './usePiaClient';
 import useSuggestedQuestions from './useSuggestedQuestions';
-import version from '../version';
+// TODO: remove SUPPORTED_DEPRECATED_PARAMS and mapDeprecatedParameters once the
+// deprecated `parameters` prop is removed from CioPiaProps.
+const SUPPORTED_DEPRECATED_PARAMS = {
+    guard: { camelKey: 'guard', isObject: false },
+    num_results: { camelKey: 'numResults', isObject: false },
+    numResults: { camelKey: 'numResults', isObject: false },
+    pre_filter_expression: { camelKey: 'preFilterExpression', isObject: true },
+    preFilterExpression: { camelKey: 'preFilterExpression', isObject: true },
+    fmt_options: { camelKey: 'fmtOptions', isObject: true },
+    fmtOptions: { camelKey: 'fmtOptions', isObject: true },
+};
+function mapDeprecatedParameters(params) {
+    if (!params)
+        return undefined;
+    const mapped = {};
+    let hasEntries = false;
+    for (const [key, value] of Object.entries(params)) {
+        const config = SUPPORTED_DEPRECATED_PARAMS[key];
+        if (!config)
+            continue;
+        hasEntries = true;
+        if (config.isObject && typeof value === 'string') {
+            try {
+                mapped[config.camelKey] = JSON.parse(value);
+            }
+            catch {
+                mapped[config.camelKey] = value;
+            }
+        }
+        else {
+            mapped[config.camelKey] = value;
+        }
+    }
+    return hasEntries ? mapped : undefined;
+}
 export default function useCioPia(props) {
-    const { apiKey, itemId, variationId, threadId: providedThreadId, cioClient: providedClient, suggestedQuestionsParameters, parameters, formatImageUrl, } = props;
-    const [generatedThreadId] = useState(() => crypto.randomUUID());
-    const threadId = providedThreadId || generatedThreadId;
-    const client = useMemo(() => {
-        if (providedClient)
-            return providedClient;
-        return new MockConstructorIOClient({
-            apiKey,
-            sendTrackingEvents: true,
-            version: `cio-ui-pia-${version}`,
-        });
-    }, [apiKey, providedClient]);
+    const { apiKey, itemId, variationId, threadId: providedThreadId, cioClient: providedClient, suggestedQuestionsParameters, answerParameters, parameters, formatImageUrl, } = props;
+    const { cioClient: client, threadId } = usePiaClient({
+        apiKey,
+        threadId: providedThreadId,
+        cioClient: providedClient,
+    });
+    const mappedDeprecated = mapDeprecatedParameters(parameters);
+    const mergedSuggestedParams = mappedDeprecated || suggestedQuestionsParameters
+        ? { ...mappedDeprecated, ...suggestedQuestionsParameters }
+        : undefined;
+    const mergedAnswerParams = mappedDeprecated || answerParameters ? { ...mappedDeprecated, ...answerParameters } : undefined;
     const suggestedQuestions = useSuggestedQuestions({
         itemId,
         variationId,
         threadId,
         cioClient: client,
-        parameters: suggestedQuestionsParameters,
-        requestParameters: parameters,
+        parameters: mergedSuggestedParams,
     });
     const answers = useAnswerResults({
         itemId,
         variationId,
         threadId,
         cioClient: client,
-        parameters,
+        parameters: mergedAnswerParams,
         formatImageUrl,
     });
     return {

package/lib/mjs/hooks/usePiaClient.js

@@ -0,0 +1,17 @@
+import { useMemo, useState } from 'react';
+import ConstructorIOClient from '@constructor-io/constructorio-client-javascript';
+import version from '../version';
+export default function usePiaClient({ apiKey, threadId: providedThreadId, cioClient: providedClient, }) {
+    const [generatedThreadId] = useState(() => crypto.randomUUID());
+    const threadId = providedThreadId || generatedThreadId;
+    const client = useMemo(() => {
+        if (providedClient)
+            return providedClient;
+        return new ConstructorIOClient({
+            apiKey,
+            sendTrackingEvents: true,
+            version: `cio-ui-pia-${version}`,
+        });
+    }, [apiKey, providedClient]);
+    return { cioClient: client, threadId };
+}

package/lib/mjs/hooks/useRecsPod.js

@@ -0,0 +1,129 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { AgentRequestError } from '../errors';
+import { translate } from '../utils/translate';
+import { RECS_FALLBACK_TITLE, RECS_LOADING_TITLE, RECS_UNSUPPORTED_REQUEST } from '../constants';
+const DEFAULT_STRATEGY = 'complementary_items';
+/**
+ * Owns everything a recommendations pod shows: one request on mount, one on every refinement,
+ * and the title that belongs to whichever of those is happening right now.
+ *
+ * The previous items are deliberately kept while a new request is in flight, so a refinement
+ * swaps the products without collapsing the row they sit in. The title is the one thing that does
+ * change, so the shopper can see the pod reacting to what they asked for.
+ */
+export default function useRecsPod({ itemId, variationId, threadId, cioClient, parameters, formatImageUrl, translations, }) {
+    const [result, setResult] = useState(null);
+    const [isLoading, setIsLoading] = useState(true);
+    const [error, setError] = useState(null);
+    const [hasUnsupportedInput, setHasUnsupportedInput] = useState(false);
+    const [lastShopperInput, setLastShopperInput] = useState('');
+    // Counts requests so a slow response cannot overwrite a newer one. There is no
+    // AbortController in this library, so the older request still completes; its result is
+    // simply dropped.
+    const requestIdRef = useRef(0);
+    // Mirrored into a ref so it never becomes a fetch dependency. It is commonly written inline by
+    // the caller, which would give it a new identity on every render and refetch forever.
+    const formatImageUrlRef = useRef(formatImageUrl);
+    useEffect(() => {
+        formatImageUrlRef.current = formatImageUrl;
+    }, [formatImageUrl]);
+    const strategy = parameters?.strategy || DEFAULT_STRATEGY;
+    const { numResults, defaultTitle } = parameters || {};
+    const fetchResult = useCallback((shopperInput, source) => {
+        // TODO: once getRecs is added to the JS client SDK, replace this guard+cast
+        // with a direct call: cioClient.agent.getRecs({...})
+        const getRecs = cioClient?.agent?.getRecs;
+        if (!cioClient || !getRecs) {
+            if (cioClient && !getRecs) {
+                console.info('[CioPia] getRecs is not available on the client SDK yet.');
+            }
+            setIsLoading(false);
+            return;
+        }
+        requestIdRef.current += 1;
+        const requestId = requestIdRef.current;
+        const isCurrent = () => requestId === requestIdRef.current;
+        setIsLoading(true);
+        setError(null);
+        setHasUnsupportedInput(false);
+        getRecs
+            .call(cioClient.agent, {
+            itemId,
+            variationId,
+            threadId,
+            strategy,
+            shopperInput,
+            numResults,
+            formatImageUrl: formatImageUrlRef.current,
+        })
+            .then((fetchedResult) => {
+            if (!isCurrent())
+                return;
+            setResult(fetchedResult);
+            setLastShopperInput(shopperInput || '');
+        })
+            .catch((err) => {
+            if (!isCurrent())
+                return;
+            const failure = err instanceof Error ? err : new Error('Error fetching recommendations');
+            const status = failure instanceof AgentRequestError ? failure.status : undefined;
+            if (status === 400) {
+                // A 400 means the request we built was malformed, which is our bug, not the
+                // shopper's. Make it loud so it is caught in development.
+                console.error('Constructor PIA: the recommendations request was rejected.', failure);
+            }
+            // A rejected input changes nothing but the input, so the response on screen stays.
+            // Only text the shopper wrote can be rejected this way: an option is a label the API
+            // suggested, so blaming their input for it would point at the wrong thing entirely.
+            if (status === 422 && source === 'input') {
+                setHasUnsupportedInput(true);
+                return;
+            }
+            setError(failure);
+        })
+            .finally(() => {
+            if (!isCurrent())
+                return;
+            setIsLoading(false);
+        });
+    }, 
+    // Every dependency is a primitive. `formatImageUrl` is read through a ref instead, so a
+    // caller writing it inline cannot restart the request on every render.
+    [cioClient, itemId, variationId, threadId, strategy, numResults]);
+    useEffect(() => {
+        fetchResult();
+    }, [fetchResult]);
+    const refine = useCallback((text, source) => {
+        const refinementText = text.trim();
+        if (!refinementText)
+            return;
+        fetchResult(refinementText, source);
+    }, [fetchResult]);
+    // The title belonging to the last response we kept. `defaultTitle` is the caller's last resort
+    // for a response that carried items but no title of its own.
+    const settledTitle = result?.title || defaultTitle || '';
+    let title = settledTitle;
+    if (isLoading) {
+        // The loading copy wins whether or not a title is held, so a refinement announces itself
+        // rather than leaving the previous personalization above products that no longer match it.
+        title = translate(RECS_LOADING_TITLE, translations);
+    }
+    else if (!hasUnsupportedInput && (error || result?.status === 'partial')) {
+        // Either the request failed or it came back degraded, so the personalized title cannot be
+        // trusted. Any products it did carry are still worth showing under a generic title.
+        title = translate(RECS_FALLBACK_TITLE, translations);
+    }
+    return {
+        title,
+        // Normalized so every caller can treat "nothing to render" as a single case. Our own adapter
+        // never returns an empty array, but `cioClient` is a public prop and a consumer-supplied client
+        // can. Note `[]` is truthy, so `|| null` would not catch it.
+        items: result?.items?.length ? result.items : null,
+        refinement: result?.refinement || null,
+        isLoading,
+        error,
+        inputError: hasUnsupportedInput ? translate(RECS_UNSUPPORTED_REQUEST, translations) : null,
+        lastShopperInput,
+        refine,
+    };
+}

package/lib/mjs/hooks/useSuggestedQuestions.js

@@ -1,35 +1,22 @@
-import { useCallback, useEffect, useState } from 'react';
-const fetchSuggestedQuestions = async ({ client, itemId, variationId, threadId, parameters, requestParameters, }) => {
-    const response = await client.agent.getSuggestedQuestions({
-        itemId,
-        variationId,
-        threadId,
-        parameters,
-        requestParameters,
-    });
-    return response.questions;
-};
-export default function useSuggestedQuestions({ itemId, variationId, threadId, cioClient, parameters, requestParameters, }) {
+import { useCallback, useEffect, useMemo, useState } from 'react';
+export default function useSuggestedQuestions({ itemId, variationId, threadId, cioClient, parameters, }) {
     const [questions, setQuestions] = useState([]);
     const [isLoading, setIsLoading] = useState(false);
     const [error, setError] = useState(null);
-    // Serialize to a primitive so an object-literal prop doesn't retrigger the auto-fetch effect each render.
-    const requestParametersKey = JSON.stringify(requestParameters);
+    const serializedParameters = useMemo(() => JSON.stringify(parameters), [parameters]);
     const fetchResult = useCallback(() => {
         if (!cioClient)
             return;
         setIsLoading(true);
         setError(null);
-        fetchSuggestedQuestions({
-            client: cioClient,
-            itemId,
-            variationId,
+        cioClient.agent.pia
+            .getSuggestedQuestions(itemId, {
             threadId,
-            parameters,
-            requestParameters,
+            variationId,
+            ...parameters,
         })
-            .then((fetchedQuestions) => {
-            setQuestions(fetchedQuestions);
+            .then((response) => {
+            setQuestions(response.questions);
             setError(null);
         })
             .catch((err) => {
@@ -38,8 +25,9 @@ export default function useSuggestedQuestions({ itemId, variationId, threadId, c
             .finally(() => {
             setIsLoading(false);
         });
-        // eslint-disable-next-line react-hooks/exhaustive-deps -- primitive deps prevent refetch loop
-    }, [cioClient, itemId, variationId, threadId, parameters?.numResults, requestParametersKey]);
+        // parameters is serialized via serializedParameters to prevent refetch on identity changes
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [cioClient, itemId, variationId, threadId, serializedParameters]);
     useEffect(() => {
         fetchResult();
     }, [fetchResult]);

package/lib/mjs/hooks/useViewportTracking.js

@@ -1,6 +1,7 @@
 import { useCallback, useEffect, useRef } from 'react';
 const FLUSH_INTERVAL_MS = 5 * 60 * 1000;
-export default function useViewportTracking({ tracking, questions, }) {
+const DEFAULT_VIEW_THRESHOLD = 0.5;
+export default function useViewportTracking({ tracking, questions, viewThreshold = DEFAULT_VIEW_THRESHOLD, }) {
     const nodeRef = useRef(null);
     const observerRef = useRef(null);
     const intervalRef = useRef(null);
@@ -48,7 +49,7 @@ export default function useViewportTracking({ tracking, questions, }) {
                 entryTimeRef.current = null;
                 trackingRef.current.trackOutOfView();
             }
-        }, { threshold: 0.5 });
+        }, { threshold: viewThreshold });
         observer.observe(element);
         observerRef.current = observer;
         intervalRef.current = setInterval(flush, FLUSH_INTERVAL_MS);

package/lib/mjs/styles.css

@@ -9,6 +9,7 @@
 @import './components/CioPia/CioPiaStyles.css';
 @import './components/ConversationHistory/ConversationHistoryStyles.css';
 @import './components/PiaConversation/PiaConversationStyles.css';
+@import './components/CioPiaRecs/CioPiaRecsStyles.css';
 
 .cio-pia-container {
   font-family: 'Inter', sans-serif;

package/lib/mjs/types.js

@@ -3,4 +3,3 @@ export var FeedbackType;
     FeedbackType["UP"] = "up";
     FeedbackType["DOWN"] = "down";
 })(FeedbackType || (FeedbackType = {}));
-export * from './hooks/mocks/types';

package/lib/mjs/utils/classNames.js

@@ -0,0 +1,9 @@
+/**
+ * Joins class names, dropping the falsy ones, so a conditional class can be written inline.
+ *
+ * Deliberately not `clsx` or `classnames`: neither is a dependency of this package, and the copy of
+ * `clsx` in the tree belongs to `@constructor-io/constructorio-ui-components`, which is a peer
+ * dependency - importing it here would work locally and break in a consumer that hoists
+ * differently. Worth revisiting if this ever needs to accept objects or nested arrays.
+ */
+export const cx = (...parts) => parts.filter(Boolean).join(' ');

package/lib/mjs/utils/recs.js

@@ -0,0 +1,9 @@
+import { translate } from './translate';
+import { RECS_REFINEMENT_LABEL } from '../constants';
+/**
+ * The line that introduces the refinement options. Prefers the prompt the API sent, so our
+ * copy and theirs cannot drift.
+ */
+export function resolveRefinementQuestion(refinement, translations) {
+    return refinement?.question || translate(RECS_REFINEMENT_LABEL, translations);
+}

package/lib/mjs/utils/translate.js

@@ -1,4 +1,4 @@
-import { DISCLAIMER_TEXT } from '../constants';
+import { DISCLAIMER_TEXT, RECS_FALLBACK_TITLE, RECS_INPUT_PLACEHOLDER, RECS_LOADING_TITLE, RECS_REFINEMENT_LABEL, RECS_UNSUPPORTED_REQUEST, } from '../constants';
 const defaultTranslations = {
     'Any questions about this product?': 'Any questions about this product?',
     'Ask anything': 'Ask anything',
@@ -8,6 +8,11 @@ const defaultTranslations = {
     'Learn More.': 'Learn More.',
     'Ask about this product': 'Ask about this product',
     'Add to Cart': 'Add to Cart',
+    [RECS_LOADING_TITLE]: RECS_LOADING_TITLE,
+    [RECS_FALLBACK_TITLE]: RECS_FALLBACK_TITLE,
+    [RECS_UNSUPPORTED_REQUEST]: RECS_UNSUPPORTED_REQUEST,
+    [RECS_REFINEMENT_LABEL]: RECS_REFINEMENT_LABEL,
+    [RECS_INPUT_PLACEHOLDER]: RECS_INPUT_PLACEHOLDER,
 };
 /**
  * Translates a word using the provided translations object.

package/lib/mjs/version.js

@@ -1 +1 @@
-export default '2.10.4';
+export default '2.12.0';

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

@@ -1,38 +1,3 @@
 import React from 'react';
-import { IncludeComponentOverrides, IncludeRenderProps } from '@constructor-io/constructorio-ui-components';
-import MockConstructorIOClient from '../../hooks/mocks/MockConstructorIOClient';
-import { CioPiaRenderProps, CioPiaComponentOverrides, Callbacks, CioPiaDisplayConfigs, Translations, SuggestedQuestionsParameters, Formatters, ProductCardDisplayProps } 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;
-    /** The product display name, sent with tracking events. */
-    itemName: string;
-    /** 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, onProductCardClick, onFeedback). */
-    callbacks?: Callbacks;
-    /** Custom component overrides via reactNode or render props functions. */
-    componentOverrides?: CioPiaComponentOverrides;
-    /** Formatter functions for transforming data before display. */
-    formatters?: Formatters;
-    /** Props forwarded to the ProductCard rendered inside the carousel. */
-    productCardProps?: ProductCardDisplayProps;
-    /** UI string translations for internationalization. */
-    translations?: Translations;
-    /** Parameters for the suggested questions request. */
-    suggestedQuestionsParameters?: SuggestedQuestionsParameters;
-    /**
-     * Extra query parameters appended to PIA API requests (e.g. `ef-*` test cell params).
-     * Define outside the component or wrap with useMemo to avoid unnecessary re-renders.
-     */
-    parameters?: Record<string, string | number | boolean>;
-}
+import type { CioPiaProps } from './types';
 export default function CioPia(props: CioPiaProps): React.JSX.Element;

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

@@ -0,0 +1,4 @@
+import React from 'react';
+import type { CioPiaProps } from './types';
+/** The question-and-answer experience: `mode: 'default'`, `mode: 'conversation'`, and the modal. */
+export default function CioPiaQna(props: CioPiaProps): React.JSX.Element;

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

@@ -1,3 +1,4 @@
 import CioPia from './CioPia';
 export * from './CioPia';
+export type { CioPiaProps } from './types';
 export default CioPia;

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

@@ -0,0 +1,55 @@
+import { IncludeComponentOverrides, IncludeRenderProps } from '@constructor-io/constructorio-ui-components';
+import { CioPiaRenderProps, CioPiaComponentOverrides, Callbacks, CioPiaDisplayConfigs, CioPiaTrackingConfigs, Translations, SuggestedQuestionsParameters, AnswerRequestParameters, RecsPodParameters, Formatters, ProductCardDisplayProps } from '../../types';
+import type { CioClient } from '../../hooks/usePiaClient';
+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;
+    /** The product display name, sent with tracking events. */
+    itemName: string;
+    /** 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?: CioClient;
+    /** Display configuration options (mode, type, showFeedback, etc.). */
+    displayConfigs?: CioPiaDisplayConfigs;
+    /** Tracking configuration options (viewThreshold, etc.). */
+    trackingConfigs?: CioPiaTrackingConfigs;
+    /** Callback handlers for user interactions (onQuestionSubmit, onProductCardClick, onFeedback). */
+    callbacks?: Callbacks;
+    /** Custom component overrides via reactNode or render props functions. */
+    componentOverrides?: CioPiaComponentOverrides;
+    /** Formatter functions for transforming data before display. */
+    formatters?: Formatters;
+    /** Props forwarded to the ProductCard rendered inside the carousel. */
+    productCardProps?: ProductCardDisplayProps;
+    /** UI string translations for internationalization. */
+    translations?: Translations;
+    /** Parameters for the suggested questions request. */
+    suggestedQuestionsParameters?: SuggestedQuestionsParameters;
+    /** Parameters for the answer request. */
+    answerParameters?: AnswerRequestParameters;
+    /** Parameters for the recommendations request, used by `mode: 'recommendations'`. */
+    recsPodParameters?: RecsPodParameters;
+    /**
+     * @deprecated Use `answerParameters` and `suggestedQuestionsParameters` instead.
+     *
+     * Only the following keys are forwarded (snake_case or camelCase accepted):
+     *
+     * Suggested-questions endpoint:
+     * - `num_results` / `numResults` → numResults
+     * - `pre_filter_expression` / `preFilterExpression` → preFilterExpression (JSON-parsed if string)
+     *
+     * Answer endpoint:
+     * - `guard` → guard
+     * - `pre_filter_expression` / `preFilterExpression` → preFilterExpression (JSON-parsed if string)
+     * - `fmt_options` / `fmtOptions` → fmtOptions (JSON-parsed if string)
+     *
+     * All other keys (e.g. `ef-*`) are silently dropped.
+     * Typed parameters take precedence over values specified here.
+     */
+    parameters?: Record<string, string | number | boolean>;
+}