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

package/lib/cjs/components/CioPia/CioPia.js

@@ -1,103 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
-const react_1 = tslib_1.__importStar(require("react"));
-const constructorio_ui_components_1 = require("@constructor-io/constructorio-ui-components");
-const Input_1 = tslib_1.__importDefault(require("../Input/Input"));
-const SuggestedQuestionsContainer_1 = tslib_1.__importDefault(require("../SuggestedQuestionsContainer/SuggestedQuestionsContainer"));
-const useCioPia_1 = tslib_1.__importDefault(require("../../hooks/useCioPia"));
-const useConversation_1 = tslib_1.__importDefault(require("../../hooks/useConversation"));
-const useTracking_1 = tslib_1.__importDefault(require("../../hooks/useTracking"));
-const useViewportTracking_1 = tslib_1.__importDefault(require("../../hooks/useViewportTracking"));
-const useViewportCallbacks_1 = tslib_1.__importDefault(require("../../hooks/useViewportCallbacks"));
-const ErrorBlock_1 = tslib_1.__importDefault(require("../Error/ErrorBlock"));
-const LoadingSkeleton_1 = tslib_1.__importDefault(require("../LoadingSkeleton/LoadingSkeleton"));
-const translate_1 = require("../../utils/translate");
-const PiaInlineAnswer_1 = tslib_1.__importDefault(require("../PiaInlineAnswer/PiaInlineAnswer"));
-const PiaModal_1 = tslib_1.__importDefault(require("../PiaConversation/PiaModal"));
-const PiaConversation_1 = tslib_1.__importDefault(require("../PiaConversation/PiaConversation"));
-// eslint-disable-next-line complexity
+const react_1 = tslib_1.__importDefault(require("react"));
+const CioPiaQna_1 = tslib_1.__importDefault(require("./CioPiaQna"));
+const CioPiaRecs_1 = tslib_1.__importDefault(require("../CioPiaRecs/CioPiaRecs"));
 function CioPia(props) {
-    var _a;
-    const { apiKey, itemId, itemName, threadId, variationId, cioClient, displayConfigs, componentOverrides, callbacks, formatters, productCardProps, children, translations, suggestedQuestionsParameters, parameters, } = props;
-    const { learnMoreUrl, showFeedback, mode = 'default', type = 'inline', showPreviousItems, disclaimerPosition = 'bottom', } = displayConfigs || {};
-    const isConversation = mode === 'conversation' || type === 'modal';
-    const { priceCurrency } = productCardProps || {};
-    const pia = (0, useCioPia_1.default)({
-        apiKey,
-        itemId,
-        threadId,
-        variationId,
-        cioClient,
-        suggestedQuestionsParameters,
-        parameters,
-        formatImageUrl: formatters === null || formatters === void 0 ? void 0 : formatters.formatImageUrl,
-    });
-    const tracking = (0, useTracking_1.default)({
-        cioClient: pia.cioClient,
-        itemId,
-        itemName,
-        variationId,
-        threadId: pia.threadId,
-    });
-    const { currentQuestion, displayedQuestions, conversationHistory, currentAnswer, currentItems, isLoading, error, context, handleSubmitQuestion, handleQuestionClick, handleInputFocus, handleFeedback, resetState, } = (0, useConversation_1.default)({ pia, itemId, isConversation, callbacks, tracking });
-    const { containerRef: viewportContainerRef } = (0, useViewportTracking_1.default)({
-        tracking,
-        questions: displayedQuestions,
-    });
-    const { containerRef: callbackContainerRef } = (0, useViewportCallbacks_1.default)({ callbacks, context });
-    const containerRef = (0, react_1.useCallback)((node) => {
-        viewportContainerRef(node);
-        callbackContainerRef(node);
-    }, [viewportContainerRef, callbackContainerRef]);
-    const qnaResultId = (_a = pia.answers.data) === null || _a === void 0 ? void 0 : _a.qna_result_id;
-    const renderProps = {
-        items: currentItems,
-        isLoading,
-        error,
-        currentAnswer,
-        currentQuestion,
-        displayedQuestions,
-        handleSubmitQuestion,
-        conversationHistory,
-    };
-    const conversationHistoryProps = {
-        conversationHistory,
-        isLoading,
-        error,
-        currentItems,
-        showFeedback,
-        showPreviousItems,
-        learnMoreUrl,
-        disclaimerPosition,
-        translations,
-        callbacks,
-        componentOverrides,
-        displayedQuestions,
-        handleSubmitQuestion,
-        handleQuestionClick,
-        handleFeedback,
-        onResultClick: tracking.trackResultClick,
-        qnaResultId,
-        containerRef,
-        onInputFocus: handleInputFocus,
-        priceCurrency,
-    };
-    if (type === 'modal') {
-        return (react_1.default.createElement(PiaModal_1.default, { initialQuestions: pia.suggestedQuestions.data, handleSubmitQuestion: handleSubmitQuestion, handleQuestionClick: handleQuestionClick, containerRef: containerRef, isLoading: isLoading, componentOverrides: componentOverrides, translations: translations, onInputFocus: handleInputFocus, onClose: resetState },
-            react_1.default.createElement(PiaConversation_1.default, Object.assign({}, conversationHistoryProps))));
+    var _a, _b;
+    const mode = (_b = (_a = props.displayConfigs) === null || _a === void 0 ? void 0 : _a.mode) !== null && _b !== void 0 ? _b : 'default';
+    if (mode === 'recommendations') {
+        return react_1.default.createElement(CioPiaRecs_1.default, Object.assign({}, props));
     }
-    if (isConversation)
-        return react_1.default.createElement(PiaConversation_1.default, Object.assign({}, conversationHistoryProps));
-    // Default inline mode
-    return (react_1.default.createElement("div", { ref: containerRef, className: 'cio-pia-container', "data-testid": 'cio-pia-container' },
-        react_1.default.createElement(constructorio_ui_components_1.RenderPropsWrapper, { props: renderProps, override: children || (componentOverrides === null || componentOverrides === void 0 ? void 0 : componentOverrides.reactNode) },
-            react_1.default.createElement("p", { className: 'cio-pia-title', "data-testid": 'cio-pia-title' }, (0, translate_1.translate)('Any questions about this product?', translations)),
-            react_1.default.createElement(Input_1.default, { onSubmit: handleSubmitQuestion, onFocus: handleInputFocus, value: currentQuestion, translations: translations, componentOverride: componentOverrides === null || componentOverrides === void 0 ? void 0 : componentOverrides.input }),
-            isLoading && react_1.default.createElement(LoadingSkeleton_1.default, { componentOverride: componentOverrides === null || componentOverrides === void 0 ? void 0 : componentOverrides.loading }),
-            !isLoading && error && react_1.default.createElement(ErrorBlock_1.default, { message: (error === null || error === void 0 ? void 0 : error.message) || 'Unexpected error' }),
-            !isLoading && !error && (react_1.default.createElement(react_1.default.Fragment, null,
-                currentAnswer && (react_1.default.createElement(PiaInlineAnswer_1.default, { currentAnswer: currentAnswer, currentItems: currentItems, showFeedback: showFeedback, learnMoreUrl: learnMoreUrl, disclaimerPosition: disclaimerPosition, translations: translations, callbacks: callbacks, componentOverrides: componentOverrides, onFeedback: handleFeedback, onResultClick: tracking.trackResultClick, question: currentQuestion, qnaResultId: qnaResultId, priceCurrency: priceCurrency })),
-                react_1.default.createElement(SuggestedQuestionsContainer_1.default, { questions: displayedQuestions, onQuestionClick: handleQuestionClick, componentOverride: componentOverrides === null || componentOverrides === void 0 ? void 0 : componentOverrides.suggestedQuestions }))))));
+    return react_1.default.createElement(CioPiaQna_1.default, Object.assign({}, props));
 }
 exports.default = CioPia;

package/lib/cjs/components/CioPia/CioPiaQna.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const react_1 = tslib_1.__importStar(require("react"));
+const constructorio_ui_components_1 = require("@constructor-io/constructorio-ui-components");
+const Input_1 = tslib_1.__importDefault(require("../Input/Input"));
+const SuggestedQuestionsContainer_1 = tslib_1.__importDefault(require("../SuggestedQuestionsContainer/SuggestedQuestionsContainer"));
+const SuggestedQuestionsSkeleton_1 = tslib_1.__importDefault(require("../SuggestedQuestionsContainer/SuggestedQuestionsSkeleton"));
+const useCioPia_1 = tslib_1.__importDefault(require("../../hooks/useCioPia"));
+const useConversation_1 = tslib_1.__importDefault(require("../../hooks/useConversation"));
+const useTracking_1 = tslib_1.__importDefault(require("../../hooks/useTracking"));
+const useViewportTracking_1 = tslib_1.__importDefault(require("../../hooks/useViewportTracking"));
+const useViewportCallbacks_1 = tslib_1.__importDefault(require("../../hooks/useViewportCallbacks"));
+const ErrorBlock_1 = tslib_1.__importDefault(require("../Error/ErrorBlock"));
+const LoadingSkeleton_1 = tslib_1.__importDefault(require("../LoadingSkeleton/LoadingSkeleton"));
+const translate_1 = require("../../utils/translate");
+const PiaInlineAnswer_1 = tslib_1.__importDefault(require("../PiaInlineAnswer/PiaInlineAnswer"));
+const PiaModal_1 = tslib_1.__importDefault(require("../PiaConversation/PiaModal"));
+const PiaConversation_1 = tslib_1.__importDefault(require("../PiaConversation/PiaConversation"));
+/** The question-and-answer experience: `mode: 'default'`, `mode: 'conversation'`, and the modal. */
+// eslint-disable-next-line complexity
+function CioPiaQna(props) {
+    var _a;
+    const { apiKey, itemId, itemName, threadId, variationId, cioClient, displayConfigs, componentOverrides, callbacks, formatters, productCardProps, children, translations, suggestedQuestionsParameters, answerParameters, parameters, trackingConfigs, } = props;
+    const { learnMoreUrl, showFeedback, mode = 'default', type = 'inline', showPreviousItems, disclaimerPosition = 'bottom', } = displayConfigs || {};
+    const isConversation = mode === 'conversation' || type === 'modal';
+    const { priceCurrency } = productCardProps || {};
+    const pia = (0, useCioPia_1.default)({
+        apiKey,
+        itemId,
+        threadId,
+        variationId,
+        cioClient,
+        suggestedQuestionsParameters,
+        answerParameters,
+        parameters,
+        formatImageUrl: formatters === null || formatters === void 0 ? void 0 : formatters.formatImageUrl,
+    });
+    const tracking = (0, useTracking_1.default)({
+        cioClient: pia.cioClient,
+        itemId,
+        itemName,
+        variationId,
+        threadId: pia.threadId,
+    });
+    const { currentQuestion, displayedQuestions, conversationHistory, currentAnswer, currentItems, isLoading, error, context, handleSubmitQuestion, handleQuestionClick, handleInputFocus, handleFeedback, resetState, } = (0, useConversation_1.default)({ pia, itemId, isConversation, callbacks, tracking });
+    const { containerRef: viewportContainerRef } = (0, useViewportTracking_1.default)({
+        tracking,
+        questions: displayedQuestions,
+        viewThreshold: trackingConfigs === null || trackingConfigs === void 0 ? void 0 : trackingConfigs.viewThreshold,
+    });
+    const { containerRef: callbackContainerRef } = (0, useViewportCallbacks_1.default)({ callbacks, context });
+    const containerRef = (0, react_1.useCallback)((node) => {
+        viewportContainerRef(node);
+        callbackContainerRef(node);
+    }, [viewportContainerRef, callbackContainerRef]);
+    const qnaResultId = (_a = pia.answers.data) === null || _a === void 0 ? void 0 : _a.qna_result_id;
+    // The text bars stand in for the answer alone, so they track the answer request only. The question
+    // row keeps the combined `isLoading`: the follow-up questions that refill it arrive with the
+    // answer, so the row is waiting on either request.
+    const isAnswerLoading = pia.answers.isLoading;
+    const renderProps = {
+        items: currentItems,
+        isLoading,
+        error,
+        currentAnswer,
+        currentQuestion,
+        displayedQuestions,
+        handleSubmitQuestion,
+        conversationHistory,
+    };
+    const conversationHistoryProps = {
+        conversationHistory,
+        isLoading,
+        error,
+        currentItems,
+        showFeedback,
+        showPreviousItems,
+        learnMoreUrl,
+        disclaimerPosition,
+        translations,
+        callbacks,
+        componentOverrides,
+        displayedQuestions,
+        handleSubmitQuestion,
+        handleQuestionClick,
+        handleFeedback,
+        onResultClick: tracking.trackResultClick,
+        qnaResultId,
+        containerRef,
+        onInputFocus: handleInputFocus,
+        priceCurrency,
+    };
+    if (type === 'modal') {
+        return (react_1.default.createElement(PiaModal_1.default, { initialQuestions: pia.suggestedQuestions.data, handleSubmitQuestion: handleSubmitQuestion, handleQuestionClick: handleQuestionClick, containerRef: containerRef, isLoading: isLoading, componentOverrides: componentOverrides, translations: translations, onInputFocus: handleInputFocus, onClose: resetState },
+            react_1.default.createElement(PiaConversation_1.default, Object.assign({}, conversationHistoryProps))));
+    }
+    if (isConversation)
+        return react_1.default.createElement(PiaConversation_1.default, Object.assign({}, conversationHistoryProps));
+    // Default inline mode
+    return (react_1.default.createElement("div", { ref: containerRef, className: 'cio-pia-container', "data-testid": 'cio-pia-container' },
+        react_1.default.createElement(constructorio_ui_components_1.RenderPropsWrapper, { props: renderProps, override: children || (componentOverrides === null || componentOverrides === void 0 ? void 0 : componentOverrides.reactNode) },
+            react_1.default.createElement("p", { className: 'cio-pia-title', "data-testid": 'cio-pia-title' }, (0, translate_1.translate)('Any questions about this product?', translations)),
+            react_1.default.createElement(Input_1.default, { onSubmit: handleSubmitQuestion, onFocus: handleInputFocus, value: currentQuestion, translations: translations, componentOverride: componentOverrides === null || componentOverrides === void 0 ? void 0 : componentOverrides.input }),
+            isAnswerLoading && react_1.default.createElement(LoadingSkeleton_1.default, { componentOverride: componentOverrides === null || componentOverrides === void 0 ? void 0 : componentOverrides.loading }),
+            !isAnswerLoading && error && react_1.default.createElement(ErrorBlock_1.default, { message: (error === null || error === void 0 ? void 0 : error.message) || 'Unexpected error' }),
+            !isAnswerLoading && !error && currentAnswer && (react_1.default.createElement(PiaInlineAnswer_1.default, { currentAnswer: currentAnswer, currentItems: currentItems, showFeedback: showFeedback, learnMoreUrl: learnMoreUrl, disclaimerPosition: disclaimerPosition, translations: translations, callbacks: callbacks, componentOverrides: componentOverrides, onFeedback: handleFeedback, onResultClick: tracking.trackResultClick, question: currentQuestion, qnaResultId: qnaResultId, priceCurrency: priceCurrency })),
+            isLoading && react_1.default.createElement(SuggestedQuestionsSkeleton_1.default, null),
+            !isLoading && !error && (react_1.default.createElement(SuggestedQuestionsContainer_1.default, { questions: displayedQuestions, onQuestionClick: handleQuestionClick, componentOverride: componentOverrides === null || componentOverrides === void 0 ? void 0 : componentOverrides.suggestedQuestions })))));
+}
+exports.default = CioPiaQna;

package/lib/cjs/components/CioPia/CioPiaStyles.css

@@ -30,3 +30,22 @@
 .cio-pia-learn-more {
   color: inherit;
 }
+
+/* Neutral placeholder shown until the product image itself paints over it.
+   Set on the image element so it inherits the card's own size and corner radius. */
+.cio-pia-answer-container .cio-product-card-image {
+  background-color: rgba(0, 0, 0, 0.05);
+}
+
+/* Restores the clamped, muted look of the stock ProductCard description, which the
+   custom HTML description rendering does not inherit. */
+.cio-pia-answer-container .cio-product-card-description {
+  display: -webkit-box;
+  -webkit-line-clamp: 3;
+  -webkit-box-orient: vertical;
+  line-clamp: 3;
+  overflow: hidden;
+  font-size: 14px;
+  line-height: 20px;
+  color: #6b7280;
+}

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

@@ -46,12 +46,10 @@ function buildMergedOverrides(componentOverrides, priceSectionOverride) {
     return Object.assign(Object.assign({}, componentOverrides), { item: Object.assign(Object.assign({}, componentOverrides === null || componentOverrides === void 0 ? void 0 : componentOverrides.item), { productCard: Object.assign(Object.assign({}, (_c = componentOverrides === null || componentOverrides === void 0 ? void 0 : componentOverrides.item) === null || _c === void 0 ? void 0 : _c.productCard), { content: Object.assign(Object.assign({}, content), defaults) }) }) });
 }
 function PiaCustomCarousel({ items, componentOverrides, callbacks, onResultClick, question, qnaResultId, translations, priceCurrency, }) {
-    const wrapperRef = (0, react_1.useRef)(null);
     const { onAddToCart } = callbacks || {};
     const addToCartHandler = (0, react_1.useCallback)((event, product) => {
         onAddToCart === null || onAddToCart === void 0 ? void 0 : onAddToCart(product, event);
     }, [onAddToCart]);
-    // Determine to use user-defined click handler or default behavior
     const productClickHandler = (0, react_1.useCallback)((item) => {
         const position = items.findIndex((i) => i.id === item.id);
         if (onResultClick && question) {
@@ -65,40 +63,37 @@ function PiaCustomCarousel({ items, componentOverrides, callbacks, onResultClick
             window.open(item.url, '_blank', 'noopener,noreferrer');
         }
     }, [callbacks, items, onResultClick, question, qnaResultId]);
-    // Set up event listener for product card clicks
-    (0, react_1.useEffect)(() => {
-        const el = wrapperRef.current;
-        if (!el)
-            return undefined;
-        const handleClick = (e) => {
-            const { product } = e.detail;
-            if (product) {
-                productClickHandler(product);
-            }
-        };
-        el.addEventListener(constructorio_ui_components_1.CIO_EVENTS.productCard.click, handleClick);
-        return () => {
-            el.removeEventListener(constructorio_ui_components_1.CIO_EVENTS.productCard.click, handleClick);
-        };
-    }, [productClickHandler]);
     const priceSectionOverride = (0, react_1.useMemo)(() => (priceCurrency ? createPriceSectionOverride(priceCurrency) : undefined), [priceCurrency]);
+    const clickHandlerProps = (0, react_1.useMemo)(() => ({
+        onProductClick: productClickHandler,
+        onAddToCart: onAddToCart ? addToCartHandler : undefined,
+    }), [productClickHandler, onAddToCart, addToCartHandler]);
     const mergedOverrides = (0, react_1.useMemo)(() => {
-        var _a;
+        var _a, _b;
         const baseOverrides = buildMergedOverrides(componentOverrides, priceSectionOverride);
+        // Override priority: carousel.reactNode → item.reactNode → item.productCard.reactNode → default ProductCard.
+        // The casts are required because the override signatures don't declare these extra props,
+        // but consumers receive them as part of the render-props contract documented in CioPiaProps.
+        const carouselOverride = baseOverrides.reactNode;
+        if (typeof carouselOverride === 'function') {
+            return Object.assign(Object.assign({}, baseOverrides), { reactNode: (props) => carouselOverride(Object.assign(Object.assign({}, props), clickHandlerProps)) });
+        }
         const cardOverrides = (_a = baseOverrides.item) === null || _a === void 0 ? void 0 : _a.productCard;
-        // The carousel never passes onAddToCart down and the card hides the button without it, so
-        // re-render the card with the handler. A full card override owns its own layout - skip it.
-        if (!onAddToCart || (cardOverrides === null || cardOverrides === void 0 ? void 0 : cardOverrides.reactNode)) {
-            return baseOverrides;
+        const itemOverride = (_b = baseOverrides.item) === null || _b === void 0 ? void 0 : _b.reactNode;
+        if (typeof itemOverride === 'function') {
+            return Object.assign(Object.assign({}, baseOverrides), { item: Object.assign(Object.assign({}, baseOverrides.item), { reactNode: (props) => itemOverride(Object.assign(Object.assign({}, props), clickHandlerProps)) }) });
+        }
+        if (typeof (cardOverrides === null || cardOverrides === void 0 ? void 0 : cardOverrides.reactNode) === 'function') {
+            const originalReactNode = cardOverrides.reactNode;
+            return Object.assign(Object.assign({}, baseOverrides), { item: Object.assign(Object.assign({}, baseOverrides.item), { productCard: Object.assign(Object.assign({}, cardOverrides), { reactNode: (props) => originalReactNode(Object.assign(Object.assign({}, props), clickHandlerProps)) }) }) });
         }
-        const addToCartText = (0, translate_1.translate)('Add to Cart', translations);
-        return Object.assign(Object.assign({}, baseOverrides), { item: Object.assign(Object.assign({}, baseOverrides.item), { productCard: Object.assign(Object.assign({}, cardOverrides), { reactNode: ({ product }) => (react_1.default.createElement(constructorio_ui_components_1.ProductCard, { product: product, className: 'w-full h-full', addToCartText: addToCartText, onAddToCart: addToCartHandler, componentOverrides: cardOverrides })) }) }) });
-    }, [componentOverrides, priceSectionOverride, onAddToCart, translations, addToCartHandler]);
-    // If there are no items, do not render the carousel
+        // Default: render ProductCard with handlers directly
+        const addToCartText = onAddToCart ? (0, translate_1.translate)('Add to Cart', translations) : undefined;
+        return Object.assign(Object.assign({}, baseOverrides), { item: Object.assign(Object.assign({}, baseOverrides.item), { productCard: Object.assign(Object.assign({}, cardOverrides), { reactNode: ({ product }) => (react_1.default.createElement(constructorio_ui_components_1.ProductCard, { product: product, className: 'w-full h-full', addToCartText: addToCartText, onAddToCart: clickHandlerProps.onAddToCart, onProductClick: clickHandlerProps.onProductClick, componentOverrides: cardOverrides })) }) }) });
+    }, [componentOverrides, priceSectionOverride, clickHandlerProps, onAddToCart, translations]);
     if (items.length === 0) {
         return null;
     }
-    return (react_1.default.createElement("div", { ref: wrapperRef },
-        react_1.default.createElement(constructorio_ui_components_1.Carousel, { items: items, componentOverrides: mergedOverrides })));
+    return react_1.default.createElement(constructorio_ui_components_1.Carousel, { items: items, componentOverrides: mergedOverrides });
 }
 exports.default = PiaCustomCarousel;

package/lib/cjs/components/CioPiaRecs/CioPiaRecs.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const react_1 = tslib_1.__importStar(require("react"));
+const constructorio_ui_components_1 = require("@constructor-io/constructorio-ui-components");
+const PiaCustomCarousel_1 = tslib_1.__importDefault(require("../CioPia/PiaCustomCarousel"));
+const RecsPodRefinement_1 = tslib_1.__importDefault(require("./RecsPodRefinement"));
+const RecsCarouselSkeleton_1 = tslib_1.__importDefault(require("./RecsCarouselSkeleton"));
+const usePiaClient_1 = tslib_1.__importDefault(require("../../hooks/usePiaClient"));
+const useRecsPod_1 = tslib_1.__importDefault(require("../../hooks/useRecsPod"));
+const useViewportCallbacks_1 = tslib_1.__importDefault(require("../../hooks/useViewportCallbacks"));
+const classNames_1 = require("../../utils/classNames");
+/**
+ * A pod of AI-curated product suggestions: a personalized title, a row of products, and short
+ * options for narrowing them down. It asks no questions and makes no Q&A requests, so a retailer
+ * can use it on its own.
+ *
+ * Renders nothing at all once a request has settled with no products, so whatever the retailer
+ * already had in that slot shows through instead of an empty shell. That is the default: a caller
+ * that supplied its own root — `children` or `componentOverrides.reactNode` — still gets it in that
+ * state, with `error` available, and decides what belongs there.
+ */
+function CioPiaRecs(props) {
+    const { apiKey, itemId, threadId, variationId, cioClient, componentOverrides, callbacks, formatters, productCardProps, children, translations, recsPodParameters, } = props;
+    const { priceCurrency } = productCardProps || {};
+    const { showInput = true, numResults } = recsPodParameters || {};
+    const { answer: answerOverride, carousel: carouselOverride, loading: loadingOverride, reactNode: rootOverride, } = componentOverrides || {};
+    const { cioClient: client, threadId: resolvedThreadId } = (0, usePiaClient_1.default)({
+        apiKey,
+        threadId,
+        cioClient,
+    });
+    const { title, items, refinement, isLoading, error, inputError, lastShopperInput, refine } = (0, useRecsPod_1.default)({
+        itemId,
+        variationId,
+        threadId: resolvedThreadId,
+        cioClient: client,
+        parameters: recsPodParameters,
+        formatImageUrl: formatters === null || formatters === void 0 ? void 0 : formatters.formatImageUrl,
+        translations,
+    });
+    const context = (0, react_1.useMemo)(() => ({ itemId, threadId: resolvedThreadId }), [itemId, resolvedThreadId]);
+    const { containerRef } = (0, useViewportCallbacks_1.default)({ callbacks, context });
+    const handleInputFocus = (0, react_1.useCallback)(() => { var _a; return (_a = callbacks === null || callbacks === void 0 ? void 0 : callbacks.onFocus) === null || _a === void 0 ? void 0 : _a.call(callbacks, context); }, [callbacks, context]);
+    const refineFromOption = (0, react_1.useCallback)((text) => refine(text, 'option'), [refine]);
+    const refineFromInput = (0, react_1.useCallback)((text) => refine(text, 'input'), [refine]);
+    const renderProps = {
+        items,
+        isLoading,
+        error,
+        currentAnswer: title,
+        currentQuestion: lastShopperInput,
+        displayedQuestions: ((refinement === null || refinement === void 0 ? void 0 : refinement.options) || []).map((value) => ({ value })),
+        // A caller's own root gets the free-text behavior: whatever it submits is the shopper's, so a
+        // rejection belongs under their input.
+        handleSubmitQuestion: refineFromInput,
+        conversationHistory: [],
+    };
+    // Nothing of ours to show. Rendering no markup at all is the default, so whatever the retailer
+    // already had in that slot shows through instead of an empty shell. TODO: an interim, not a
+    // settled decision — the empty-state design and the shape of a hard failure are both still open.
+    // A caller who supplied its own root still gets it, with `error` in hand, so a consumer can put
+    // its own message here.
+    if (!isLoading && !items && !children && !rootOverride)
+        return null;
+    return (react_1.default.createElement("div", { ref: containerRef, className: (0, classNames_1.cx)('cio-pia-container', 'cio-pia-recs-pod', isLoading && 'cio-pia-recs-pod--loading'), "data-testid": 'cio-pia-recs-pod' },
+        react_1.default.createElement(constructorio_ui_components_1.RenderPropsWrapper, { props: renderProps, override: children || rootOverride },
+            title && (react_1.default.createElement(constructorio_ui_components_1.RenderPropsWrapper, { props: { text: title }, override: answerOverride === null || answerOverride === void 0 ? void 0 : answerOverride.reactNode },
+                react_1.default.createElement("h3", { key: title, className: 'cio-pia-recs-pod__title' }, title))),
+            react_1.default.createElement("div", { className: 'cio-pia-recs-pod__products', "data-testid": 'cio-pia-recs-pod-products' }, isLoading || !items ? (react_1.default.createElement(RecsCarouselSkeleton_1.default, { count: numResults !== null && numResults !== void 0 ? numResults : items === null || items === void 0 ? void 0 : items.length, componentOverride: loadingOverride })) : (react_1.default.createElement(PiaCustomCarousel_1.default, { items: items, componentOverrides: carouselOverride, callbacks: callbacks, translations: translations, priceCurrency: priceCurrency }))),
+            react_1.default.createElement(RecsPodRefinement_1.default, { refinement: refinement, isLoading: isLoading, inputError: inputError, showInput: showInput, translations: translations, componentOverrides: componentOverrides, onRefine: refineFromOption, onSubmit: refineFromInput, onInputFocus: handleInputFocus }))));
+}
+exports.default = CioPiaRecs;

package/lib/cjs/components/CioPiaRecs/CioPiaRecsStyles.css

@@ -0,0 +1,138 @@
+.cio-pia-recs-pod {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  width: 100%;
+}
+
+/*
+ * The title is the one part of the pod that changes on a refinement, so it fades in rather than
+ * snapping. `CioPiaRecs` keys the node on the title, which remounts it and replays this.
+ *
+ * This is a fade-in on the arriving title, not a cross-fade: React removes the outgoing text
+ * synchronously, so there is nothing left on screen to fade out.
+ */
+.cio-pia-recs-pod__title {
+  min-height: 20px;
+  margin: 0;
+  font-size: 16px;
+  font-weight: 500;
+  color: #14151a;
+  text-align: start;
+  animation: recs-pod-title-fade-in 200ms ease-in;
+}
+
+@keyframes recs-pod-title-fade-in {
+  from {
+    opacity: 0;
+  }
+
+  to {
+    opacity: 1;
+  }
+}
+
+/* Holds the products, and the placeholders that stand in for them while a request is in flight */
+.cio-pia-recs-pod__products {
+  display: flex;
+  flex-direction: column;
+}
+
+/* Options and the free-text box share one row, wrapping on narrow screens */
+.cio-pia-recs-pod__refinement {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 8px;
+}
+
+.cio-pia-recs-pod__refinement-label {
+  font-size: 12px;
+  font-weight: 500;
+  color: #0f1324;
+}
+
+.cio-pia-recs-pod__input {
+  display: flex;
+  flex-direction: column;
+  flex: 1 1 200px;
+  min-width: 200px;
+}
+
+/* Nothing in the row is clickable while its contents are being replaced */
+.cio-pia-recs-pod--loading .cio-pia-recs-pod__refinement {
+  pointer-events: none;
+}
+
+/* Placeholders, shaped like the real content so the page does not jump when data lands */
+.cio-pia-recs-skeleton {
+  display: flex;
+  gap: 8px;
+  width: 100%;
+}
+
+/*
+ * This one holds the real carousel, arrows and all, so nothing in it is clickable while its
+ * contents are being replaced.
+ */
+.cio-pia-recs-skeleton--carousel {
+  flex: 1 1 auto;
+  pointer-events: none;
+}
+
+/*
+ * The only two measurements taken from the package, both from the card's own image
+ * (`min-h-[224px] rounded-2xl`). The image is what gives a card its height, so these are what stop
+ * the refinement row moving when the products land. Everything else about the card - its
+ * background, radius, shadow, padding, and how many fit across - comes from the carousel itself.
+ */
+.cio-pia-recs-skeleton__image {
+  min-height: 224px;
+  border-radius: 16px;
+}
+
+/* Bar heights are the line boxes of the text they stand in for, so the card totals the same */
+.cio-pia-recs-skeleton__price {
+  width: 40%;
+  height: 28px;
+}
+
+.cio-pia-recs-skeleton__title {
+  width: 80%;
+  height: 24px;
+}
+
+.cio-pia-recs-skeleton__desc {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.cio-pia-recs-skeleton__desc .skeleton-bar {
+  height: 18px;
+}
+
+/* Short last line, the way a wrapped sentence ends */
+.cio-pia-recs-skeleton__desc .skeleton-bar:last-child {
+  width: 60%;
+}
+
+.cio-pia-recs-skeleton--options {
+  width: auto;
+}
+
+.cio-pia-recs-skeleton--options .cio-pia-recs-skeleton__block {
+  height: 26px;
+  width: 96px;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .cio-pia-recs-skeleton__block,
+  .cio-pia-recs-skeleton__image,
+  .cio-pia-recs-skeleton__price,
+  .cio-pia-recs-skeleton__title,
+  .cio-pia-recs-skeleton__desc .skeleton-bar,
+  .cio-pia-recs-pod__title {
+    animation: none;
+  }
+}

package/lib/cjs/components/CioPiaRecs/RecsCarouselSkeleton.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const react_1 = tslib_1.__importDefault(require("react"));
+const constructorio_ui_components_1 = require("@constructor-io/constructorio-ui-components");
+/** The widest band the carousel lays out. Narrower ones need no count: its viewport clips them. */
+const DEFAULT_COUNT = 6;
+/**
+ * Grey bars standing in for a card's own sections. The card around them - white background,
+ * rounded corners, shadow, padding - and the row it sits in are the real ones, so nothing here has
+ * to know their measurements.
+ *
+ * `RenderPropsWrapper` draws an override in place of a section rather than alongside it, so these
+ * appear even though the placeholder carries no image, price or name of its own.
+ *
+ * A caller's own `productCard` overrides are deliberately not merged in, unlike the real row in
+ * `PiaCustomCarousel`: the placeholders below are empty objects, so a caller's section renderer
+ * would be handed a product with every field `undefined`.
+ */
+const CARD_SKELETON = {
+    item: {
+        productCard: {
+            image: {
+                reactNode: () => (react_1.default.createElement("div", { className: 'skeleton-bar cio-pia-recs-skeleton__image', "data-testid": 'cio-pia-recs-skeleton-card' })),
+            },
+            content: {
+                price: { reactNode: () => react_1.default.createElement("div", { className: 'skeleton-bar cio-pia-recs-skeleton__price' }) },
+                title: { reactNode: () => react_1.default.createElement("div", { className: 'skeleton-bar cio-pia-recs-skeleton__title' }) },
+                description: {
+                    // Two lines, not one. The card clamps its description at three lines and stretches every
+                    // card in a row to the tallest of them, so a single line lands short of where real
+                    // products settle.
+                    reactNode: () => (react_1.default.createElement("div", { className: 'cio-pia-recs-skeleton__desc' },
+                        react_1.default.createElement("div", { className: 'skeleton-bar' }),
+                        react_1.default.createElement("div", { className: 'skeleton-bar' }))),
+                },
+            },
+        },
+    },
+};
+/**
+ * Placeholders exist only to give the carousel something to lay out. They deliberately carry no
+ * `id` and no `name`: `ProductCard` spreads those into `data-cnstrc-item-*`, and React omits an
+ * attribute whose value is `undefined`, so a loading pod emits no product data attributes at all.
+ */
+const placeholderItems = (count) => Array.from({ length: count }, () => ({}));
+/**
+ * The product row, greyed out. It uses the real carousel rather than a set of measurements copied
+ * out of the package, so its padding, its gaps, how many cards it fits at the current width and its
+ * arrows are all right by construction. Matching the real heights is what keeps the page from
+ * jumping when the data lands.
+ */
+function RecsCarouselSkeleton({ count, componentOverride, }) {
+    const skeleton = (react_1.default.createElement("div", { className: 'cio-pia-recs-skeleton cio-pia-recs-skeleton--carousel', "data-testid": 'cio-pia-recs-skeleton-carousel', "aria-hidden": 'true' },
+        react_1.default.createElement(constructorio_ui_components_1.Carousel, { items: placeholderItems(count !== null && count !== void 0 ? count : DEFAULT_COUNT), componentOverrides: CARD_SKELETON })));
+    return (react_1.default.createElement(constructorio_ui_components_1.RenderPropsWrapper, { props: { skeleton }, override: componentOverride === null || componentOverride === void 0 ? void 0 : componentOverride.reactNode }, skeleton));
+}
+exports.default = RecsCarouselSkeleton;

package/lib/cjs/components/CioPiaRecs/RecsOptionsSkeleton.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const react_1 = tslib_1.__importDefault(require("react"));
+const DEFAULT_COUNT = 3;
+/**
+ * The refinement options, greyed out. Matching the real height is what keeps the row from
+ * collapsing and shifting the page when the options land.
+ *
+ * Takes no override, the same way `SuggestedQuestionsSkeleton` takes none: `componentOverrides.
+ * loading` stands in for the band above this one, and a caller who replaced it keeps these pills
+ * underneath, exactly as a caller who replaces the answer skeleton in question-and-answer keeps the
+ * question pills under theirs.
+ */
+function RecsOptionsSkeleton({ count }) {
+    return (react_1.default.createElement("div", { className: 'cio-pia-recs-skeleton cio-pia-recs-skeleton--options', "data-testid": 'cio-pia-recs-skeleton-options', "aria-hidden": 'true' }, Array.from({ length: count !== null && count !== void 0 ? count : DEFAULT_COUNT }, (_, index) => (react_1.default.createElement("div", { key: index, className: 'skeleton-bar cio-pia-recs-skeleton__block' })))));
+}
+exports.default = RecsOptionsSkeleton;