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

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/stories/assets/storybook-styles.css

@@ -25,8 +25,8 @@ div.link-list {
   }
 }
 
-@media all and (-ms-high-contrast:none) {
-div.link-list {
+@media all and (-ms-high-contrast: none) {
+  div.link-list {
     display: -ms-grid;
     -ms-grid-columns: 1fr 1fr;
     -ms-grid-rows: 1fr 1fr;
@@ -38,20 +38,23 @@ a.link-item {
   padding: 20px;
   border: 1px solid #00000010;
   border-radius: 5px;
-  transition: background 150ms ease-out, border 150ms ease-out, transform 150ms ease-out;
+  transition:
+    background 150ms ease-out,
+    border 150ms ease-out,
+    transform 150ms ease-out;
   color: #333333;
   display: flex;
   align-items: flex-start;
 }
 
 a.link-item:hover {
-  border-color: #1EA7FD50;
+  border-color: #1ea7fd50;
   transform: translate3d(0, -3px, 0);
   box-shadow: rgba(0, 0, 0, 0.08) 0 3px 10px 0;
 }
 
 a.link-item:active {
-  border-color: #1EA7FD;
+  border-color: #1ea7fd;
   transform: translate3d(0, 0, 0);
 }
 
@@ -81,8 +84,8 @@ span.badge {
   font-size: 11px;
   line-height: 12px;
   font-weight: 700;
-  background: #E7FDD8;
-  color: #66BF3C;
+  background: #e7fdd8;
+  color: #66bf3c;
   padding: 4px 12px;
   margin-right: 10px;
   vertical-align: top;
@@ -100,10 +103,9 @@ div.badge-wrapper code {
   display: inline-block;
 }
 
-
 .badge.tip {
-  background: #E7FDD8;
-  color: #66BF3C;
+  background: #e7fdd8;
+  color: #66bf3c;
 }
 
 .badge.note {

package/lib/mjs/version.js

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

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

@@ -0,0 +1,11 @@
+import React from 'react';
+import { CioPiaRenderProps } from '../../types';
+import { translate } from '../../utils/translate';
+import type { CheckoutTrigger } from './types';
+interface CheckoutTriggerBarProps {
+    triggers: CheckoutTrigger[];
+    state: CioPiaRenderProps;
+    translations?: Parameters<typeof translate>[1];
+}
+export default function CheckoutTriggerBar({ triggers, state, translations, }: CheckoutTriggerBarProps): React.JSX.Element | null;
+export {};

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

@@ -1,4 +1,4 @@
 import CioPia from './CioPia';
 export * from './CioPia';
-export type { CioPiaProps } from './types';
+export type { CioPiaProps, CheckoutTrigger } from './types';
 export default CioPia;

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

@@ -1,6 +1,43 @@
+import { ReactNode } from 'react';
 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';
+/**
+ * A single checkout entry point rendered inside the PIA `default` mode.
+ * The merchant owns the checkout flow itself (typically the `@constructor-io/constructorio-ui-checkout`
+ * `CheckoutFlowProvider`); PIA only surfaces the button(s) that start it.
+ */
+export interface CheckoutTrigger {
+    /** Stable identifier for the trigger — used as React key and forwarded to `renderButton`. */
+    id: string;
+    /** Button label. Defaults to "Checkout". */
+    label?: string;
+    /** Disables the button. Forwarded to `renderButton`, which is responsible for applying it. */
+    disabled?: boolean;
+    /**
+     * Predicate deciding whether this trigger should render. Called with the same
+     * render-props snapshot the `children`/`componentOverrides.reactNode` render callback
+     * receives, so consumers can gate on conversation state (e.g. "at least one answer
+     * shown", "at least two turns"). Defaults to always visible.
+     *
+     * `state.conversationHistory` is only filled in `conversation` mode and the modal; in
+     * `default` mode it stays empty, so gate on `currentAnswer` there.
+     */
+    triggerWhen?: (state: CioPiaRenderProps) => boolean;
+    /** Custom button renderer. When provided, `label` / `disabled` are passed through but styling is your call. */
+    renderButton?: (props: {
+        onClick: () => void;
+        label: string;
+        disabled?: boolean;
+        id: string;
+    }) => ReactNode;
+    /**
+     * Fires when the button is clicked. The merchant wires this to their checkout entry
+     * (e.g. `flow.start()` from `useCheckoutFlow`). Receives the render-props snapshot so
+     * the handler can seed the checkout with the current answer/items/conversation.
+     */
+    onTrigger: (state: CioPiaRenderProps) => void;
+}
 export interface CioPiaProps extends IncludeRenderProps<CioPiaRenderProps>, IncludeComponentOverrides<CioPiaComponentOverrides> {
     /** Your Constructor.io API key. */
     apiKey: string;
@@ -18,6 +55,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. */
@@ -26,6 +65,11 @@ export interface CioPiaProps extends IncludeRenderProps<CioPiaRenderProps>, Incl
     formatters?: Formatters;
     /** Props forwarded to the ProductCard rendered inside the carousel. */
     productCardProps?: ProductCardDisplayProps;
+    /**
+     * One or more checkout entry points. Rendered in `default` and `conversation` modes and
+     * in the modal, after the answer; ignored in `recommendations` mode.
+     */
+    checkoutTriggers?: CheckoutTrigger[];
     /** UI string translations for internationalization. */
     translations?: Translations;
     /** Parameters for the suggested questions request. */

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/components/PiaConversation/PiaConversation.d.ts

@@ -1,4 +1,4 @@
-import React from 'react';
+import React, { ReactNode } from 'react';
 import { FeedbackType, Item, Question } from '../../types';
 import { ConversationHistoryProps } from '../ConversationHistory/ConversationHistory';
 export interface PiaConversationProps extends ConversationHistoryProps {
@@ -10,5 +10,6 @@ export interface PiaConversationProps extends ConversationHistoryProps {
     onResultClick?: (item: Item, position: number, question: string, qnaResultId?: string) => void;
     qnaResultId?: string;
     onInputFocus?: () => void;
+    checkoutElement?: ReactNode;
 }
-export default function PiaConversation({ conversationHistory, isLoading, error, currentItems, showFeedback, showPreviousItems, learnMoreUrl, disclaimerPosition, translations, callbacks, componentOverrides, displayedQuestions, handleSubmitQuestion, handleQuestionClick, containerRef, handleFeedback, onResultClick, qnaResultId, onInputFocus, priceCurrency, }: PiaConversationProps): React.JSX.Element;
+export default function PiaConversation({ conversationHistory, isLoading, error, currentItems, showFeedback, showPreviousItems, learnMoreUrl, disclaimerPosition, translations, callbacks, componentOverrides, displayedQuestions, handleSubmitQuestion, handleQuestionClick, containerRef, handleFeedback, onResultClick, qnaResultId, onInputFocus, priceCurrency, checkoutElement, }: PiaConversationProps): 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/index.d.ts

@@ -1,6 +1,6 @@
 import CioPia from './components/CioPia';
 export { default as CioPia } from './components/CioPia';
-export type { CioPiaProps } from './components/CioPia';
+export type { CioPiaProps, CheckoutTrigger } from './components/CioPia';
 export { sanitizeHtml, renderMarkdown } from './utils/contentTransformers';
 export type { RenderMarkdownOptions, SanitizeOptions } from './utils/contentTransformers';
 export { AgentRequestError } from './errors';

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.15.0";
 export default _default;

package/package.json

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