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

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

@@ -1,98 +1,10 @@
-import React, { useCallback } from 'react';
-import { RenderPropsWrapper, } from '@constructor-io/constructorio-ui-components';
-import Input from '../Input/Input';
-import SuggestedQuestionsContainer from '../SuggestedQuestionsContainer/SuggestedQuestionsContainer';
-import useCioPia from '../../hooks/useCioPia';
-import useConversation from '../../hooks/useConversation';
-import useTracking from '../../hooks/useTracking';
-import useViewportTracking from '../../hooks/useViewportTracking';
-import useViewportCallbacks from '../../hooks/useViewportCallbacks';
-import ErrorBlock from '../Error/ErrorBlock';
-import LoadingSkeleton from '../LoadingSkeleton/LoadingSkeleton';
-import { translate } from '../../utils/translate';
-import PiaInlineAnswer from '../PiaInlineAnswer/PiaInlineAnswer';
-import PiaModal from '../PiaConversation/PiaModal';
-import PiaConversation from '../PiaConversation/PiaConversation';
-// eslint-disable-next-line complexity
+import React from 'react';
+import CioPiaQna from './CioPiaQna';
+import CioPiaRecs from '../CioPiaRecs/CioPiaRecs';
 export default function CioPia(props) {
-    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 = useCioPia({
-        apiKey,
-        itemId,
-        threadId,
-        variationId,
-        cioClient,
-        suggestedQuestionsParameters,
-        parameters,
-        formatImageUrl: formatters?.formatImageUrl,
-    });
-    const tracking = useTracking({
-        cioClient: pia.cioClient,
-        itemId,
-        itemName,
-        variationId,
-        threadId: pia.threadId,
-    });
-    const { currentQuestion, displayedQuestions, conversationHistory, currentAnswer, currentItems, isLoading, error, context, handleSubmitQuestion, handleQuestionClick, handleInputFocus, handleFeedback, resetState, } = useConversation({ pia, itemId, isConversation, callbacks, tracking });
-    const { containerRef: viewportContainerRef } = useViewportTracking({
-        tracking,
-        questions: displayedQuestions,
-    });
-    const { containerRef: callbackContainerRef } = useViewportCallbacks({ callbacks, context });
-    const containerRef = useCallback((node) => {
-        viewportContainerRef(node);
-        callbackContainerRef(node);
-    }, [viewportContainerRef, callbackContainerRef]);
-    const qnaResultId = pia.answers.data?.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.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 })));
+    const mode = props.displayConfigs?.mode ?? 'default';
+    if (mode === 'recommendations') {
+        return React.createElement(CioPiaRecs, { ...props });
     }
-    if (isConversation)
-        return React.createElement(PiaConversation, { ...conversationHistoryProps });
-    // Default inline mode
-    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, onFocus: handleInputFocus, value: currentQuestion, translations: translations, componentOverride: componentOverrides?.input }),
-            isLoading && React.createElement(LoadingSkeleton, { componentOverride: componentOverrides?.loading }),
-            !isLoading && error && React.createElement(ErrorBlock, { message: error?.message || 'Unexpected error' }),
-            !isLoading && !error && (React.createElement(React.Fragment, null,
-                currentAnswer && (React.createElement(PiaInlineAnswer, { 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.createElement(SuggestedQuestionsContainer, { questions: displayedQuestions, onQuestionClick: handleQuestionClick, componentOverride: componentOverrides?.suggestedQuestions }))))));
+    return React.createElement(CioPiaQna, { ...props });
 }

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

@@ -0,0 +1,106 @@
+import React, { useCallback } from 'react';
+import { RenderPropsWrapper } from '@constructor-io/constructorio-ui-components';
+import Input from '../Input/Input';
+import SuggestedQuestionsContainer from '../SuggestedQuestionsContainer/SuggestedQuestionsContainer';
+import SuggestedQuestionsSkeleton from '../SuggestedQuestionsContainer/SuggestedQuestionsSkeleton';
+import useCioPia from '../../hooks/useCioPia';
+import useConversation from '../../hooks/useConversation';
+import useTracking from '../../hooks/useTracking';
+import useViewportTracking from '../../hooks/useViewportTracking';
+import useViewportCallbacks from '../../hooks/useViewportCallbacks';
+import ErrorBlock from '../Error/ErrorBlock';
+import LoadingSkeleton from '../LoadingSkeleton/LoadingSkeleton';
+import { translate } from '../../utils/translate';
+import PiaInlineAnswer from '../PiaInlineAnswer/PiaInlineAnswer';
+import PiaModal from '../PiaConversation/PiaModal';
+import PiaConversation from '../PiaConversation/PiaConversation';
+/** The question-and-answer experience: `mode: 'default'`, `mode: 'conversation'`, and the modal. */
+// eslint-disable-next-line complexity
+export default function CioPiaQna(props) {
+    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 = useCioPia({
+        apiKey,
+        itemId,
+        threadId,
+        variationId,
+        cioClient,
+        suggestedQuestionsParameters,
+        answerParameters,
+        parameters,
+        formatImageUrl: formatters?.formatImageUrl,
+    });
+    const tracking = useTracking({
+        cioClient: pia.cioClient,
+        itemId,
+        itemName,
+        variationId,
+        threadId: pia.threadId,
+    });
+    const { currentQuestion, displayedQuestions, conversationHistory, currentAnswer, currentItems, isLoading, error, context, handleSubmitQuestion, handleQuestionClick, handleInputFocus, handleFeedback, resetState, } = useConversation({ pia, itemId, isConversation, callbacks, tracking });
+    const { containerRef: viewportContainerRef } = useViewportTracking({
+        tracking,
+        questions: displayedQuestions,
+        viewThreshold: trackingConfigs?.viewThreshold,
+    });
+    const { containerRef: callbackContainerRef } = useViewportCallbacks({ callbacks, context });
+    const containerRef = useCallback((node) => {
+        viewportContainerRef(node);
+        callbackContainerRef(node);
+    }, [viewportContainerRef, callbackContainerRef]);
+    const qnaResultId = pia.answers.data?.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.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 });
+    // Default inline mode
+    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, onFocus: handleInputFocus, value: currentQuestion, translations: translations, componentOverride: componentOverrides?.input }),
+            isAnswerLoading && React.createElement(LoadingSkeleton, { componentOverride: componentOverrides?.loading }),
+            !isAnswerLoading && error && React.createElement(ErrorBlock, { message: error?.message || 'Unexpected error' }),
+            !isAnswerLoading && !error && currentAnswer && (React.createElement(PiaInlineAnswer, { 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.createElement(SuggestedQuestionsSkeleton, null),
+            !isLoading && !error && (React.createElement(SuggestedQuestionsContainer, { questions: displayedQuestions, onQuestionClick: handleQuestionClick, componentOverride: componentOverrides?.suggestedQuestions })))));
+}

package/lib/mjs/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/mjs/components/CioPia/PiaCustomCarousel.js

@@ -1,5 +1,5 @@
-import React, { useCallback, useRef, useEffect, useMemo } from 'react';
-import { Carousel, ProductCard, CIO_EVENTS, } from '@constructor-io/constructorio-ui-components';
+import React, { useCallback, useMemo } from 'react';
+import { Carousel, ProductCard, } from '@constructor-io/constructorio-ui-components';
 import { sanitizeHtml } from '../../utils/contentTransformers';
 import { translate } from '../../utils/translate';
 function HtmlDescription({ product }) {
@@ -55,12 +55,10 @@ function buildMergedOverrides(componentOverrides, priceSectionOverride) {
     };
 }
 export default function PiaCustomCarousel({ items, componentOverrides, callbacks, onResultClick, question, qnaResultId, translations, priceCurrency, }) {
-    const wrapperRef = useRef(null);
     const { onAddToCart } = callbacks || {};
     const addToCartHandler = useCallback((event, product) => {
         onAddToCart?.(product, event);
     }, [onAddToCart]);
-    // Determine to use user-defined click handler or default behavior
     const productClickHandler = useCallback((item) => {
         const position = items.findIndex((i) => i.id === item.id);
         if (onResultClick && question) {
@@ -74,47 +72,62 @@ export default function PiaCustomCarousel({ items, componentOverrides, callbacks
             window.open(item.url, '_blank', 'noopener,noreferrer');
         }
     }, [callbacks, items, onResultClick, question, qnaResultId]);
-    // Set up event listener for product card clicks
-    useEffect(() => {
-        const el = wrapperRef.current;
-        if (!el)
-            return undefined;
-        const handleClick = (e) => {
-            const { product } = e.detail;
-            if (product) {
-                productClickHandler(product);
-            }
-        };
-        el.addEventListener(CIO_EVENTS.productCard.click, handleClick);
-        return () => {
-            el.removeEventListener(CIO_EVENTS.productCard.click, handleClick);
-        };
-    }, [productClickHandler]);
     const priceSectionOverride = useMemo(() => (priceCurrency ? createPriceSectionOverride(priceCurrency) : undefined), [priceCurrency]);
+    const clickHandlerProps = useMemo(() => ({
+        onProductClick: productClickHandler,
+        onAddToCart: onAddToCart ? addToCartHandler : undefined,
+    }), [productClickHandler, onAddToCart, addToCartHandler]);
     const mergedOverrides = useMemo(() => {
         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 {
+                ...baseOverrides,
+                reactNode: (props) => carouselOverride({ ...props, ...clickHandlerProps }),
+            };
+        }
         const cardOverrides = baseOverrides.item?.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?.reactNode) {
-            return baseOverrides;
+        const itemOverride = baseOverrides.item?.reactNode;
+        if (typeof itemOverride === 'function') {
+            return {
+                ...baseOverrides,
+                item: {
+                    ...baseOverrides.item,
+                    reactNode: (props) => itemOverride({ ...props, ...clickHandlerProps }),
+                },
+            };
+        }
+        if (typeof cardOverrides?.reactNode === 'function') {
+            const originalReactNode = cardOverrides.reactNode;
+            return {
+                ...baseOverrides,
+                item: {
+                    ...baseOverrides.item,
+                    productCard: {
+                        ...cardOverrides,
+                        reactNode: (props) => originalReactNode({ ...props, ...clickHandlerProps }),
+                    },
+                },
+            };
         }
-        const addToCartText = translate('Add to Cart', translations);
+        // Default: render ProductCard with handlers directly
+        const addToCartText = onAddToCart ? translate('Add to Cart', translations) : undefined;
         return {
             ...baseOverrides,
             item: {
                 ...baseOverrides.item,
                 productCard: {
                     ...cardOverrides,
-                    reactNode: ({ product }) => (React.createElement(ProductCard, { product: product, className: 'w-full h-full', addToCartText: addToCartText, onAddToCart: addToCartHandler, componentOverrides: cardOverrides })),
+                    reactNode: ({ product }) => (React.createElement(ProductCard, { product: product, className: 'w-full h-full', addToCartText: addToCartText, onAddToCart: clickHandlerProps.onAddToCart, onProductClick: clickHandlerProps.onProductClick, componentOverrides: cardOverrides })),
                 },
             },
         };
-    }, [componentOverrides, priceSectionOverride, onAddToCart, translations, addToCartHandler]);
-    // If there are no items, do not render the carousel
+    }, [componentOverrides, priceSectionOverride, clickHandlerProps, onAddToCart, translations]);
     if (items.length === 0) {
         return null;
     }
-    return (React.createElement("div", { ref: wrapperRef },
-        React.createElement(Carousel, { items: items, componentOverrides: mergedOverrides })));
+    return React.createElement(Carousel, { items: items, componentOverrides: mergedOverrides });
 }

package/lib/mjs/components/CioPiaRecs/CioPiaRecs.js

@@ -0,0 +1,69 @@
+import React, { useCallback, useMemo } from 'react';
+import { RenderPropsWrapper } from '@constructor-io/constructorio-ui-components';
+import PiaCustomCarousel from '../CioPia/PiaCustomCarousel';
+import RecsPodRefinement from './RecsPodRefinement';
+import RecsCarouselSkeleton from './RecsCarouselSkeleton';
+import usePiaClient from '../../hooks/usePiaClient';
+import useRecsPod from '../../hooks/useRecsPod';
+import useViewportCallbacks from '../../hooks/useViewportCallbacks';
+import { cx } from '../../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.
+ */
+export default 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 } = usePiaClient({
+        apiKey,
+        threadId,
+        cioClient,
+    });
+    const { title, items, refinement, isLoading, error, inputError, lastShopperInput, refine } = useRecsPod({
+        itemId,
+        variationId,
+        threadId: resolvedThreadId,
+        cioClient: client,
+        parameters: recsPodParameters,
+        formatImageUrl: formatters?.formatImageUrl,
+        translations,
+    });
+    const context = useMemo(() => ({ itemId, threadId: resolvedThreadId }), [itemId, resolvedThreadId]);
+    const { containerRef } = useViewportCallbacks({ callbacks, context });
+    const handleInputFocus = useCallback(() => callbacks?.onFocus?.(context), [callbacks, context]);
+    const refineFromOption = useCallback((text) => refine(text, 'option'), [refine]);
+    const refineFromInput = useCallback((text) => refine(text, 'input'), [refine]);
+    const renderProps = {
+        items,
+        isLoading,
+        error,
+        currentAnswer: title,
+        currentQuestion: lastShopperInput,
+        displayedQuestions: (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.createElement("div", { ref: containerRef, className: cx('cio-pia-container', 'cio-pia-recs-pod', isLoading && 'cio-pia-recs-pod--loading'), "data-testid": 'cio-pia-recs-pod' },
+        React.createElement(RenderPropsWrapper, { props: renderProps, override: children || rootOverride },
+            title && (React.createElement(RenderPropsWrapper, { props: { text: title }, override: answerOverride?.reactNode },
+                React.createElement("h3", { key: title, className: 'cio-pia-recs-pod__title' }, title))),
+            React.createElement("div", { className: 'cio-pia-recs-pod__products', "data-testid": 'cio-pia-recs-pod-products' }, isLoading || !items ? (React.createElement(RecsCarouselSkeleton, { count: numResults ?? items?.length, componentOverride: loadingOverride })) : (React.createElement(PiaCustomCarousel, { items: items, componentOverrides: carouselOverride, callbacks: callbacks, translations: translations, priceCurrency: priceCurrency }))),
+            React.createElement(RecsPodRefinement, { refinement: refinement, isLoading: isLoading, inputError: inputError, showInput: showInput, translations: translations, componentOverrides: componentOverrides, onRefine: refineFromOption, onSubmit: refineFromInput, onInputFocus: handleInputFocus }))));
+}

package/lib/mjs/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/mjs/components/CioPiaRecs/RecsCarouselSkeleton.js

@@ -0,0 +1,54 @@
+import React from 'react';
+import { Carousel, RenderPropsWrapper, } from '@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.createElement("div", { className: 'skeleton-bar cio-pia-recs-skeleton__image', "data-testid": 'cio-pia-recs-skeleton-card' })),
+            },
+            content: {
+                price: { reactNode: () => React.createElement("div", { className: 'skeleton-bar cio-pia-recs-skeleton__price' }) },
+                title: { reactNode: () => React.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.createElement("div", { className: 'cio-pia-recs-skeleton__desc' },
+                        React.createElement("div", { className: 'skeleton-bar' }),
+                        React.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.
+ */
+export default function RecsCarouselSkeleton({ count, componentOverride, }) {
+    const skeleton = (React.createElement("div", { className: 'cio-pia-recs-skeleton cio-pia-recs-skeleton--carousel', "data-testid": 'cio-pia-recs-skeleton-carousel', "aria-hidden": 'true' },
+        React.createElement(Carousel, { items: placeholderItems(count ?? DEFAULT_COUNT), componentOverrides: CARD_SKELETON })));
+    return (React.createElement(RenderPropsWrapper, { props: { skeleton }, override: componentOverride?.reactNode }, skeleton));
+}

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

@@ -0,0 +1,14 @@
+import React from '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.
+ */
+export default function RecsOptionsSkeleton({ count }) {
+    return (React.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 ?? DEFAULT_COUNT }, (_, index) => (React.createElement("div", { key: index, className: 'skeleton-bar cio-pia-recs-skeleton__block' })))));
+}

package/lib/mjs/components/CioPiaRecs/RecsPodRefinement.js

@@ -0,0 +1,23 @@
+import React from 'react';
+import Input from '../Input/Input';
+import SuggestedQuestion from '../SuggestedQuestion/SuggestedQuestion';
+import { SparklesIcon } from '../icons';
+import RecsOptionsSkeleton from './RecsOptionsSkeleton';
+import { resolveRefinementQuestion } from '../../utils/recs';
+import { RECS_INPUT_PLACEHOLDER } from '../../constants';
+/**
+ * The row under the products: a prompt line, the short options the API suggested, and a box for
+ * anything it did not think of. The prompt line is held still while the rest reloads, so the row
+ * never changes height under the shopper's cursor.
+ */
+export default function RecsPodRefinement({ refinement, isLoading, inputError, showInput, translations, componentOverrides, onRefine, onSubmit, onInputFocus, }) {
+    const options = refinement?.options || [];
+    return (React.createElement("div", { className: 'cio-pia-recs-pod__refinement' },
+        React.createElement("span", { className: 'cio-pia-recs-pod__refinement-label' }, resolveRefinementQuestion(refinement, translations)),
+        isLoading ? (React.createElement(RecsOptionsSkeleton, { count: options.length || undefined })) : (options.map((option) => (React.createElement(SuggestedQuestion, { key: option, question: option, icon: React.createElement(SparklesIcon, null), onClick: () => onRefine(option) })))),
+        showInput && (React.createElement("div", { className: 'cio-pia-recs-pod__input' },
+            React.createElement(Input, { onSubmit: onSubmit, onFocus: onInputFocus, disabled: isLoading, error: inputError ?? undefined, placeholderKey: RECS_INPUT_PLACEHOLDER, 
+                // The pod's box sits in a row beside the options and submits on Enter. Q&A keeps
+                // its button; this one has none in the mocks.
+                showSendButton: false, translations: translations, componentOverride: componentOverrides?.input })))));
+}