@constructor-io/constructorio-ui-pia 2.13.1 → 2.14.0

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

@@ -4,9 +4,14 @@ const tslib_1 = require("tslib");
 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"));
+const CioPiaControl_1 = tslib_1.__importDefault(require("../CioPiaControl/CioPiaControl"));
 function CioPia(props) {
-    var _a, _b;
+    var _a, _b, _c;
     const mode = (_b = (_a = props.displayConfigs) === null || _a === void 0 ? void 0 : _a.mode) !== null && _b !== void 0 ? _b : 'default';
+    // Before the mode dispatch: a control shopper gets no widget in any mode.
+    if ((_c = props.abTest) === null || _c === void 0 ? void 0 : _c.isControl) {
+        return react_1.default.createElement(CioPiaControl_1.default, Object.assign({}, props));
+    }
     if (mode === 'recommendations') {
         return react_1.default.createElement(CioPiaRecs_1.default, Object.assign({}, props));
     }

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

@@ -22,7 +22,7 @@ const StatusRegion_1 = tslib_1.__importStar(require("../StatusRegion/StatusRegio
 // 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 { apiKey, itemId, itemName, threadId, variationId, cioClient, displayConfigs, componentOverrides, callbacks, formatters, productCardProps, children, translations, suggestedQuestionsParameters, answerParameters, parameters, trackingConfigs, abTest, } = props;
     const { learnMoreUrl, showFeedback, mode = 'default', type = 'inline', showPreviousItems, disclaimerPosition = 'bottom', } = displayConfigs || {};
     const isConversation = mode === 'conversation' || type === 'modal';
     const { priceCurrency } = productCardProps || {};
@@ -36,6 +36,7 @@ function CioPiaQna(props) {
         answerParameters,
         parameters,
         formatImageUrl: formatters === null || formatters === void 0 ? void 0 : formatters.formatImageUrl,
+        testCells: abTest === null || abTest === void 0 ? void 0 : abTest.testCells,
     });
     const tracking = (0, useTracking_1.default)({
         cioClient: pia.cioClient,

package/lib/cjs/components/CioPiaControl/CioPiaControl.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const react_1 = tslib_1.__importDefault(require("react"));
+const usePiaClient_1 = tslib_1.__importDefault(require("../../hooks/usePiaClient"));
+const useTracking_1 = tslib_1.__importDefault(require("../../hooks/useTracking"));
+const useViewportTracking_1 = tslib_1.__importDefault(require("../../hooks/useViewportTracking"));
+const NO_QUESTIONS = [];
+/**
+ * What a control-group shopper gets instead of the widget: nothing to look at, but a node the
+ * view event can be tied to, so both arms of an A/B test are measured the same way.
+ *
+ * None of the question or answer hooks mount here, so the control arm cannot issue a request.
+ */
+function CioPiaControl(props) {
+    const { apiKey, itemId, itemName, threadId, variationId, cioClient, abTest, trackingConfigs } = props;
+    const { cioClient: client, threadId: resolvedThreadId } = (0, usePiaClient_1.default)({
+        apiKey,
+        threadId,
+        cioClient,
+        testCells: abTest === null || abTest === void 0 ? void 0 : abTest.testCells,
+    });
+    const tracking = (0, useTracking_1.default)({
+        cioClient: client,
+        itemId,
+        itemName,
+        variationId,
+        threadId: resolvedThreadId,
+    });
+    const { containerRef } = (0, useViewportTracking_1.default)({
+        tracking,
+        questions: NO_QUESTIONS,
+        viewThreshold: trackingConfigs === null || trackingConfigs === void 0 ? void 0 : trackingConfigs.viewThreshold,
+        awaitQuestions: false,
+    });
+    return (react_1.default.createElement("div", { ref: containerRef, className: 'cio-pia-control-placeholder', "data-testid": 'cio-pia-control-placeholder', style: { width: 1, height: 1, padding: 0, border: 0, margin: 0, overflow: 'hidden' }, "aria-hidden": 'true' }));
+}
+exports.default = CioPiaControl;

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

@@ -20,8 +20,9 @@ const classNames_1 = require("../../utils/classNames");
  * that supplied its own root — `children` or `componentOverrides.reactNode` — still gets it in that
  * state, with `error` available, and decides what belongs there.
  */
+// eslint-disable-next-line complexity
 function CioPiaRecs(props) {
-    const { apiKey, itemId, threadId, variationId, cioClient, componentOverrides, callbacks, formatters, productCardProps, children, translations, recsPodParameters, } = props;
+    const { apiKey, itemId, threadId, variationId, cioClient, componentOverrides, callbacks, formatters, productCardProps, children, translations, recsPodParameters, abTest, } = props;
     const { priceCurrency } = productCardProps || {};
     const { showInput = true, numResults } = recsPodParameters || {};
     const { answer: answerOverride, carousel: carouselOverride, loading: loadingOverride, reactNode: rootOverride, } = componentOverrides || {};
@@ -29,6 +30,7 @@ function CioPiaRecs(props) {
         apiKey,
         threadId,
         cioClient,
+        testCells: abTest === null || abTest === void 0 ? void 0 : abTest.testCells,
     });
     const { title, items, refinement, isLoading, error, inputError, lastShopperInput, refine } = (0, useRecsPod_1.default)({
         itemId,

package/lib/cjs/hooks/useCioPia.js

@@ -40,11 +40,12 @@ function mapDeprecatedParameters(params) {
     return hasEntries ? mapped : undefined;
 }
 function useCioPia(props) {
-    const { apiKey, itemId, variationId, threadId: providedThreadId, cioClient: providedClient, suggestedQuestionsParameters, answerParameters, parameters, formatImageUrl, } = props;
+    const { apiKey, itemId, variationId, threadId: providedThreadId, cioClient: providedClient, suggestedQuestionsParameters, answerParameters, parameters, formatImageUrl, testCells, } = props;
     const { cioClient: client, threadId } = (0, usePiaClient_1.default)({
         apiKey,
         threadId: providedThreadId,
         cioClient: providedClient,
+        testCells,
     });
     const mappedDeprecated = mapDeprecatedParameters(parameters);
     const mergedSuggestedParams = mappedDeprecated || suggestedQuestionsParameters

package/lib/cjs/hooks/usePiaClient.js

@@ -4,18 +4,25 @@ const tslib_1 = require("tslib");
 const react_1 = require("react");
 const constructorio_client_javascript_1 = tslib_1.__importDefault(require("@constructor-io/constructorio-client-javascript"));
 const version_1 = tslib_1.__importDefault(require("../version"));
-function usePiaClient({ apiKey, threadId: providedThreadId, cioClient: providedClient, }) {
+function usePiaClient({ apiKey, threadId: providedThreadId, cioClient: providedClient, testCells, }) {
     const [generatedThreadId] = (0, react_1.useState)(() => crypto.randomUUID());
     const threadId = providedThreadId || generatedThreadId;
+    const serializedTestCells = (0, react_1.useMemo)(() => JSON.stringify(testCells !== null && testCells !== void 0 ? testCells : null), [testCells]);
     const client = (0, react_1.useMemo)(() => {
         if (providedClient)
             return providedClient;
-        return new constructorio_client_javascript_1.default({
-            apiKey,
-            sendTrackingEvents: true,
-            version: `cio-ui-pia-${version_1.default}`,
-        });
-    }, [apiKey, providedClient]);
+        return new constructorio_client_javascript_1.default(Object.assign({ apiKey, sendTrackingEvents: true, version: `cio-ui-pia-${version_1.default}` }, (testCells && { testCells })));
+        // testCells is compared by serializedTestCells so an inline object does not rebuild the client
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [apiKey, providedClient, serializedTestCells]);
+    // A caller's client owns its own options, so say so rather than dropping these silently.
+    (0, react_1.useEffect)(() => {
+        if (!providedClient || !testCells || Object.keys(testCells).length === 0)
+            return;
+        console.warn('[CioPia] abTest.testCells is ignored when you supply your own cioClient. Set testCells on that client instead.');
+        // serializedTestCells stands in for testCells here too
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [providedClient, serializedTestCells]);
     return { cioClient: client, threadId };
 }
 exports.default = usePiaClient;

package/lib/cjs/hooks/useViewportTracking.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const react_1 = require("react");
 const FLUSH_INTERVAL_MS = 5 * 60 * 1000;
 const DEFAULT_VIEW_THRESHOLD = 0.5;
-function useViewportTracking({ tracking, questions, viewThreshold = DEFAULT_VIEW_THRESHOLD, }) {
+function useViewportTracking({ tracking, questions, viewThreshold = DEFAULT_VIEW_THRESHOLD, awaitQuestions = true, }) {
     const nodeRef = (0, react_1.useRef)(null);
     const observerRef = (0, react_1.useRef)(null);
     const intervalRef = (0, react_1.useRef)(null);
@@ -11,10 +11,14 @@ function useViewportTracking({ tracking, questions, viewThreshold = DEFAULT_VIEW
     const entryTimeRef = (0, react_1.useRef)(null);
     const questionsRef = (0, react_1.useRef)(questions);
     const trackingRef = (0, react_1.useRef)(tracking);
+    const awaitQuestionsRef = (0, react_1.useRef)(awaitQuestions);
+    (0, react_1.useEffect)(() => {
+        awaitQuestionsRef.current = awaitQuestions;
+    }, [awaitQuestions]);
     (0, react_1.useEffect)(() => {
         const questionsJustArrived = questionsRef.current.length === 0 && questions.length > 0;
         questionsRef.current = questions;
-        if (questionsJustArrived && entryTimeRef.current) {
+        if (awaitQuestionsRef.current && questionsJustArrived && entryTimeRef.current) {
             trackingRef.current.trackView(questions);
         }
     }, [questions]);
@@ -30,7 +34,8 @@ function useViewportTracking({ tracking, questions, viewThreshold = DEFAULT_VIEW
             });
             entryTimeRef.current = null;
         }
-        if (timespansRef.current.length > 0 && questionsRef.current.length > 0) {
+        const hasPayload = !awaitQuestionsRef.current || questionsRef.current.length > 0;
+        if (timespansRef.current.length > 0 && hasPayload) {
             trackingRef.current.trackViews(questionsRef.current, [...timespansRef.current]);
             timespansRef.current = [];
         }
@@ -39,7 +44,7 @@ function useViewportTracking({ tracking, questions, viewThreshold = DEFAULT_VIEW
         const observer = new IntersectionObserver(([entry]) => {
             if (entry.isIntersecting) {
                 entryTimeRef.current = new Date().toISOString();
-                if (questionsRef.current.length > 0) {
+                if (!awaitQuestionsRef.current || questionsRef.current.length > 0) {
                     trackingRef.current.trackView(questionsRef.current);
                 }
             }

package/lib/cjs/version.js

@@ -1,3 +1,3 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.default = '2.13.1';
+exports.default = '2.14.0';

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

@@ -1,8 +1,13 @@
 import React from 'react';
 import CioPiaQna from './CioPiaQna';
 import CioPiaRecs from '../CioPiaRecs/CioPiaRecs';
+import CioPiaControl from '../CioPiaControl/CioPiaControl';
 export default function CioPia(props) {
     const mode = props.displayConfigs?.mode ?? 'default';
+    // Before the mode dispatch: a control shopper gets no widget in any mode.
+    if (props.abTest?.isControl) {
+        return React.createElement(CioPiaControl, { ...props });
+    }
     if (mode === 'recommendations') {
         return React.createElement(CioPiaRecs, { ...props });
     }

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

@@ -18,7 +18,7 @@ import StatusRegion, { answerStatusMessage } from '../StatusRegion/StatusRegion'
 /** 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 { apiKey, itemId, itemName, threadId, variationId, cioClient, displayConfigs, componentOverrides, callbacks, formatters, productCardProps, children, translations, suggestedQuestionsParameters, answerParameters, parameters, trackingConfigs, abTest, } = props;
     const { learnMoreUrl, showFeedback, mode = 'default', type = 'inline', showPreviousItems, disclaimerPosition = 'bottom', } = displayConfigs || {};
     const isConversation = mode === 'conversation' || type === 'modal';
     const { priceCurrency } = productCardProps || {};
@@ -32,6 +32,7 @@ export default function CioPiaQna(props) {
         answerParameters,
         parameters,
         formatImageUrl: formatters?.formatImageUrl,
+        testCells: abTest?.testCells,
     });
     const tracking = useTracking({
         cioClient: pia.cioClient,

package/lib/mjs/components/CioPiaControl/CioPiaControl.js

@@ -0,0 +1,34 @@
+import React from 'react';
+import usePiaClient from '../../hooks/usePiaClient';
+import useTracking from '../../hooks/useTracking';
+import useViewportTracking from '../../hooks/useViewportTracking';
+const NO_QUESTIONS = [];
+/**
+ * What a control-group shopper gets instead of the widget: nothing to look at, but a node the
+ * view event can be tied to, so both arms of an A/B test are measured the same way.
+ *
+ * None of the question or answer hooks mount here, so the control arm cannot issue a request.
+ */
+export default function CioPiaControl(props) {
+    const { apiKey, itemId, itemName, threadId, variationId, cioClient, abTest, trackingConfigs } = props;
+    const { cioClient: client, threadId: resolvedThreadId } = usePiaClient({
+        apiKey,
+        threadId,
+        cioClient,
+        testCells: abTest?.testCells,
+    });
+    const tracking = useTracking({
+        cioClient: client,
+        itemId,
+        itemName,
+        variationId,
+        threadId: resolvedThreadId,
+    });
+    const { containerRef } = useViewportTracking({
+        tracking,
+        questions: NO_QUESTIONS,
+        viewThreshold: trackingConfigs?.viewThreshold,
+        awaitQuestions: false,
+    });
+    return (React.createElement("div", { ref: containerRef, className: 'cio-pia-control-placeholder', "data-testid": 'cio-pia-control-placeholder', style: { width: 1, height: 1, padding: 0, border: 0, margin: 0, overflow: 'hidden' }, "aria-hidden": 'true' }));
+}

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

@@ -17,8 +17,9 @@ import { cx } from '../../utils/classNames';
  * that supplied its own root — `children` or `componentOverrides.reactNode` — still gets it in that
  * state, with `error` available, and decides what belongs there.
  */
+// eslint-disable-next-line complexity
 export default function CioPiaRecs(props) {
-    const { apiKey, itemId, threadId, variationId, cioClient, componentOverrides, callbacks, formatters, productCardProps, children, translations, recsPodParameters, } = props;
+    const { apiKey, itemId, threadId, variationId, cioClient, componentOverrides, callbacks, formatters, productCardProps, children, translations, recsPodParameters, abTest, } = props;
     const { priceCurrency } = productCardProps || {};
     const { showInput = true, numResults } = recsPodParameters || {};
     const { answer: answerOverride, carousel: carouselOverride, loading: loadingOverride, reactNode: rootOverride, } = componentOverrides || {};
@@ -26,6 +27,7 @@ export default function CioPiaRecs(props) {
         apiKey,
         threadId,
         cioClient,
+        testCells: abTest?.testCells,
     });
     const { title, items, refinement, isLoading, error, inputError, lastShopperInput, refine } = useRecsPod({
         itemId,

package/lib/mjs/hooks/useCioPia.js

@@ -37,11 +37,12 @@ function mapDeprecatedParameters(params) {
     return hasEntries ? mapped : undefined;
 }
 export default function useCioPia(props) {
-    const { apiKey, itemId, variationId, threadId: providedThreadId, cioClient: providedClient, suggestedQuestionsParameters, answerParameters, parameters, formatImageUrl, } = props;
+    const { apiKey, itemId, variationId, threadId: providedThreadId, cioClient: providedClient, suggestedQuestionsParameters, answerParameters, parameters, formatImageUrl, testCells, } = props;
     const { cioClient: client, threadId } = usePiaClient({
         apiKey,
         threadId: providedThreadId,
         cioClient: providedClient,
+        testCells,
     });
     const mappedDeprecated = mapDeprecatedParameters(parameters);
     const mergedSuggestedParams = mappedDeprecated || suggestedQuestionsParameters

package/lib/mjs/hooks/usePiaClient.js

@@ -1,9 +1,10 @@
-import { useMemo, useState } from 'react';
+import { useEffect, useMemo, useState } from 'react';
 import ConstructorIOClient from '@constructor-io/constructorio-client-javascript';
 import version from '../version';
-export default function usePiaClient({ apiKey, threadId: providedThreadId, cioClient: providedClient, }) {
+export default function usePiaClient({ apiKey, threadId: providedThreadId, cioClient: providedClient, testCells, }) {
     const [generatedThreadId] = useState(() => crypto.randomUUID());
     const threadId = providedThreadId || generatedThreadId;
+    const serializedTestCells = useMemo(() => JSON.stringify(testCells ?? null), [testCells]);
     const client = useMemo(() => {
         if (providedClient)
             return providedClient;
@@ -11,7 +12,18 @@ export default function usePiaClient({ apiKey, threadId: providedThreadId, cioCl
             apiKey,
             sendTrackingEvents: true,
             version: `cio-ui-pia-${version}`,
+            ...(testCells && { testCells }),
         });
-    }, [apiKey, providedClient]);
+        // testCells is compared by serializedTestCells so an inline object does not rebuild the client
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [apiKey, providedClient, serializedTestCells]);
+    // A caller's client owns its own options, so say so rather than dropping these silently.
+    useEffect(() => {
+        if (!providedClient || !testCells || Object.keys(testCells).length === 0)
+            return;
+        console.warn('[CioPia] abTest.testCells is ignored when you supply your own cioClient. Set testCells on that client instead.');
+        // serializedTestCells stands in for testCells here too
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [providedClient, serializedTestCells]);
     return { cioClient: client, threadId };
 }

package/lib/mjs/hooks/useViewportTracking.js

@@ -1,7 +1,7 @@
 import { useCallback, useEffect, useRef } from 'react';
 const FLUSH_INTERVAL_MS = 5 * 60 * 1000;
 const DEFAULT_VIEW_THRESHOLD = 0.5;
-export default function useViewportTracking({ tracking, questions, viewThreshold = DEFAULT_VIEW_THRESHOLD, }) {
+export default function useViewportTracking({ tracking, questions, viewThreshold = DEFAULT_VIEW_THRESHOLD, awaitQuestions = true, }) {
     const nodeRef = useRef(null);
     const observerRef = useRef(null);
     const intervalRef = useRef(null);
@@ -9,10 +9,14 @@ export default function useViewportTracking({ tracking, questions, viewThreshold
     const entryTimeRef = useRef(null);
     const questionsRef = useRef(questions);
     const trackingRef = useRef(tracking);
+    const awaitQuestionsRef = useRef(awaitQuestions);
+    useEffect(() => {
+        awaitQuestionsRef.current = awaitQuestions;
+    }, [awaitQuestions]);
     useEffect(() => {
         const questionsJustArrived = questionsRef.current.length === 0 && questions.length > 0;
         questionsRef.current = questions;
-        if (questionsJustArrived && entryTimeRef.current) {
+        if (awaitQuestionsRef.current && questionsJustArrived && entryTimeRef.current) {
             trackingRef.current.trackView(questions);
         }
     }, [questions]);
@@ -28,7 +32,8 @@ export default function useViewportTracking({ tracking, questions, viewThreshold
             });
             entryTimeRef.current = null;
         }
-        if (timespansRef.current.length > 0 && questionsRef.current.length > 0) {
+        const hasPayload = !awaitQuestionsRef.current || questionsRef.current.length > 0;
+        if (timespansRef.current.length > 0 && hasPayload) {
             trackingRef.current.trackViews(questionsRef.current, [...timespansRef.current]);
             timespansRef.current = [];
         }
@@ -37,7 +42,7 @@ export default function useViewportTracking({ tracking, questions, viewThreshold
         const observer = new IntersectionObserver(([entry]) => {
             if (entry.isIntersecting) {
                 entryTimeRef.current = new Date().toISOString();
-                if (questionsRef.current.length > 0) {
+                if (!awaitQuestionsRef.current || questionsRef.current.length > 0) {
                     trackingRef.current.trackView(questionsRef.current);
                 }
             }

package/lib/mjs/version.js

@@ -1 +1 @@
-export default '2.13.1';
+export default '2.14.0';

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

@@ -1,5 +1,5 @@
 import { IncludeComponentOverrides, IncludeRenderProps } from '@constructor-io/constructorio-ui-components';
-import { CioPiaRenderProps, CioPiaComponentOverrides, Callbacks, CioPiaDisplayConfigs, CioPiaTrackingConfigs, Translations, SuggestedQuestionsParameters, AnswerRequestParameters, RecsPodParameters, Formatters, ProductCardDisplayProps } from '../../types';
+import { CioPiaRenderProps, CioPiaComponentOverrides, Callbacks, CioPiaAbTest, CioPiaDisplayConfigs, CioPiaTrackingConfigs, Translations, SuggestedQuestionsParameters, AnswerRequestParameters, RecsPodParameters, Formatters, ProductCardDisplayProps } from '../../types';
 import type { CioClient } from '../../hooks/usePiaClient';
 export interface CioPiaProps extends IncludeRenderProps<CioPiaRenderProps>, IncludeComponentOverrides<CioPiaComponentOverrides> {
     /** Your Constructor.io API key. */
@@ -18,6 +18,8 @@ export interface CioPiaProps extends IncludeRenderProps<CioPiaRenderProps>, Incl
     displayConfigs?: CioPiaDisplayConfigs;
     /** Tracking configuration options (viewThreshold, etc.). */
     trackingConfigs?: CioPiaTrackingConfigs;
+    /** A/B test configuration: test cells to attach to events, and the control-group flag. */
+    abTest?: CioPiaAbTest;
     /** Callback handlers for user interactions (onQuestionSubmit, onProductCardClick, onFeedback). */
     callbacks?: Callbacks;
     /** Custom component overrides via reactNode or render props functions. */

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

@@ -0,0 +1,9 @@
+import React from 'react';
+import type { CioPiaProps } from '../CioPia/types';
+/**
+ * What a control-group shopper gets instead of the widget: nothing to look at, but a node the
+ * view event can be tied to, so both arms of an A/B test are measured the same way.
+ *
+ * None of the question or answer hooks mount here, so the control arm cannot issue a request.
+ */
+export default function CioPiaControl(props: CioPiaProps): React.JSX.Element;

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

@@ -32,6 +32,8 @@ export interface UseCioPiaProps {
     parameters?: Record<string, string | number | boolean>;
     /** Define outside the component or wrap with useCallback to avoid unnecessary re-renders. */
     formatImageUrl?: Formatters['formatImageUrl'];
+    /** Test cells to attach to tracking events. Ignored when `cioClient` is supplied. */
+    testCells?: Record<string, string>;
 }
 export interface UseCioPiaReturn {
     cioClient: {

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

@@ -4,9 +4,10 @@ export interface UsePiaClientProps {
     apiKey: string;
     threadId?: string;
     cioClient?: CioClient;
+    testCells?: Record<string, string>;
 }
 export interface UsePiaClientReturn {
     cioClient: CioClient;
     threadId: string;
 }
-export default function usePiaClient({ apiKey, threadId: providedThreadId, cioClient: providedClient, }: UsePiaClientProps): UsePiaClientReturn;
+export default function usePiaClient({ apiKey, threadId: providedThreadId, cioClient: providedClient, testCells, }: UsePiaClientProps): UsePiaClientReturn;

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

@@ -4,8 +4,13 @@ export interface UseViewportTrackingProps {
     tracking: UseTrackingReturn;
     questions: Question[];
     viewThreshold?: number;
+    /**
+     * Whether an empty `questions` array means "not loaded yet". False for a control-group
+     * placeholder, where no questions are ever fetched and the view must still be recorded.
+     */
+    awaitQuestions?: boolean;
 }
 export interface UseViewportTrackingReturn {
     containerRef: (node: HTMLDivElement | null) => void;
 }
-export default function useViewportTracking({ tracking, questions, viewThreshold, }: UseViewportTrackingProps): UseViewportTrackingReturn;
+export default function useViewportTracking({ tracking, questions, viewThreshold, awaitQuestions, }: UseViewportTrackingProps): UseViewportTrackingReturn;

package/lib/types/types.d.ts

@@ -24,6 +24,11 @@ export interface CioPiaProviderProps {
     threadId?: string;
     cioClient?: Nullable<CioClient>;
 }
+/**
+ * Display mode. `'recommendations'` is accepted but **not yet available**: the
+ * recommendations endpoint is absent from the client SDK, so that mode renders
+ * nothing. Use `'default'` or `'conversation'`.
+ */
 export type CioPiaMode = 'default' | 'conversation' | 'recommendations';
 export type CioPiaType = 'inline' | 'modal';
 export type DisclaimerPosition = 'top' | 'bottom';
@@ -34,6 +39,34 @@ export type CioPiaTrackingConfigs = {
      */
     viewThreshold?: number;
 };
+export type CioPiaAbTest = {
+    /**
+     * Test cells to attach to PIA tracking events, as `{ [testName]: cellName }`. Each entry is
+     * sent as an `ef-<testName>` parameter. Source them however you like — Constructor's docs have
+     * the page set `window.cnstrc.testCell` to a bare cell name, so label it with your test name:
+     * `{ constructorio: window.cnstrc.testCell }`. Some integrations expose a `window.cnstrc.testCells`
+     * map instead, which you can pass straight through.
+     *
+     * Ignored when you supply your own `cioClient`: that client owns its own options, so set
+     * `testCells` there instead, as a `ConstructorIOClient` constructor option. Passing both
+     * logs a warning.
+     *
+     * Empty, non-string, or whitespace-only values are silently dropped, so a cell sourced from
+     * a global that resolves to `undefined` will simply not be sent.
+     */
+    testCells?: Record<string, string>;
+    /**
+     * Mark this shopper as the A/B control group. Renders an invisible, tracking-only placeholder
+     * instead of the widget, so both arms of the test record a view event. Takes precedence over
+     * `displayConfigs.mode`. The placeholder renders neither `children` nor `componentOverrides`,
+     * and does not fire the `onView` / `onOutOfView` callbacks — the control arm reports through
+     * Constructor's own view event only.
+     *
+     * Required: stating the arm per shopper is the one thing only you can know, and leaving it
+     * out would silently put every shopper in the test arm with no control group at all.
+     */
+    isControl: boolean;
+};
 export type CioPiaDisplayConfigs = {
     learnMoreUrl?: string;
     showFeedback?: boolean;

package/lib/types/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "2.13.1";
+declare const _default: "2.14.0";
 export default _default;

package/package.json

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