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

package/lib/mjs/hooks/useSuggestedQuestions.js

@@ -1,15 +1,24 @@
-import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 export default function useSuggestedQuestions({ itemId, variationId, threadId, cioClient, parameters, }) {
     const [questions, setQuestions] = useState([]);
     const [isLoading, setIsLoading] = useState(false);
     const [error, setError] = useState(null);
     const serializedParameters = useMemo(() => JSON.stringify(parameters), [parameters]);
+    // The client is how the question is asked, not part of the question: a host that
+    // rebuilds it on render must not make the widget ask the same thing again.
+    const cioClientRef = useRef(cioClient);
+    useEffect(() => {
+        cioClientRef.current = cioClient;
+    }, [cioClient]);
+    // A client arriving where there was none is the one client change worth a fetch.
+    const hasClient = !!cioClient;
     const fetchResult = useCallback(() => {
-        if (!cioClient)
+        const client = cioClientRef.current;
+        if (!client)
             return;
         setIsLoading(true);
         setError(null);
-        cioClient.agent.pia
+        client.agent.pia
             .getSuggestedQuestions(itemId, {
             threadId,
             variationId,
@@ -27,7 +36,7 @@ export default function useSuggestedQuestions({ itemId, variationId, threadId, c
         });
         // parameters is serialized via serializedParameters to prevent refetch on identity changes
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [cioClient, itemId, variationId, threadId, serializedParameters]);
+    }, [hasClient, itemId, variationId, threadId, serializedParameters]);
     useEffect(() => {
         fetchResult();
     }, [fetchResult]);

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.0';
+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/utils/contentTransformers.d.ts

@@ -1,6 +1,6 @@
-import DOMPurify from 'dompurify';
+import DOMPurify, { type Config } from 'dompurify';
 export interface SanitizeOptions {
-    config: DOMPurify.Config;
+    config: Config;
 }
 /** Options for {@link renderMarkdown}. */
 export interface RenderMarkdownOptions {

package/lib/types/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "2.13.0";
+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.0",
+  "version": "2.14.0",
   "description": "Constructor.io AI Product Insights Agent UI library for web applications",
   "author": "Constructor.io Corporation",
   "license": "MIT",
@@ -99,7 +99,6 @@
     "@storybook/testing-library": "^0.2.1",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.2.0",
-    "@types/dompurify": "^3.0.5",
     "@types/jest": "^30.0.0",
     "@types/react": "^19.0.10",
     "@types/react-dom": "^19.0.4",
@@ -127,17 +126,19 @@
     "typescript-eslint": "^8.59.2",
     "vite": "^6.4.3",
     "vite-plugin-css-injected-by-js": "^3.5.2",
-    "webpack": "^5.98.0"
+    "webpack": "^5.104.1"
   },
   "volta": {
     "node": "22.18.0",
     "npm": "10.9.3"
   },
   "dependencies": {
-    "dompurify": "^3.4.2",
+    "dompurify": "^3.4.15",
     "marked": "^15.0.12"
   },
   "overrides": {
-    "uuid": "^11.1.1"
+    "uuid": "^11.1.1",
+    "browserslist": "^4.28.9",
+    "postcss-selector-parser": "^7.1.6"
   }
 }