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

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 })))));
+}

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/mocks/agent.js

@@ -110,6 +110,21 @@ class MockAgent {
             throw new Error(String(error));
         }
     }
+    /**
+     * Fetches one set of recommendations, in the shape the pod renders.
+     *
+     * Recommendations are not available yet: there is no endpoint to ask, so nothing is requested and
+     * an empty result is returned. The pod renders nothing in that state, which leaves whatever the
+     * retailer already had in that slot showing through. Supply a `cioClient` with your own
+     * `agent.getRecs` to drive the pod from your own data in the meantime.
+     *
+     * `props` is still declared, because it is the contract a caller's own `getRecs` implements and
+     * `useRecsPod` passes it - there is simply nothing here to send it to yet.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    async getRecs(props) {
+        return { title: '', items: null, refinement: null, status: 'complete' };
+    }
     async getAnswerResultsStream({ itemId, threadId, variationId, question, parameters, onStart, onMessage, onEnd, }) {
         if (!itemId)
             throw new Error('Item ID is required');

package/lib/mjs/hooks/useCioPia.js

@@ -1,21 +1,13 @@
-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';
 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 { cioClient: client, threadId } = usePiaClient({
+        apiKey,
+        threadId: providedThreadId,
+        cioClient: providedClient,
+    });
     const suggestedQuestions = useSuggestedQuestions({
         itemId,
         variationId,

package/lib/mjs/hooks/usePiaClient.js

@@ -0,0 +1,22 @@
+import { useMemo, useState } from 'react';
+import MockConstructorIOClient from './mocks/MockConstructorIOClient';
+import version from '../version';
+/**
+ * Resolves the client and thread ID every mode needs: the caller's client when they supplied
+ * one, otherwise a client built from the API key, plus a generated thread ID that stays stable
+ * for the life of the component.
+ */
+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 MockConstructorIOClient({
+            apiKey,
+            sendTrackingEvents: true,
+            version: `cio-ui-pia-${version}`,
+        });
+    }, [apiKey, providedClient]);
+    return { cioClient: client, threadId };
+}

package/lib/mjs/hooks/useRecsPod.js

@@ -0,0 +1,125 @@
+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) => {
+        // Nothing to ask, so settle the loading state rather than leaving the caller in a skeleton
+        // that never resolves.
+        if (!cioClient) {
+            setIsLoading(false);
+            return;
+        }
+        requestIdRef.current += 1;
+        const requestId = requestIdRef.current;
+        const isCurrent = () => requestId === requestIdRef.current;
+        setIsLoading(true);
+        setError(null);
+        setHasUnsupportedInput(false);
+        cioClient.agent
+            .getRecs({
+            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/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);