@constructor-io/constructorio-ui-pia 2.17.0 → 2.18.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +7 -273
- package/dist/constructorio-ui-pia-bundled.js +33 -33
- package/lib/cjs/components/Answer/Answer.js +2 -2
- package/lib/cjs/components/CioPia/CioPiaQna.js +12 -2
- package/lib/cjs/components/CioPiaRecs/RecsPodRefinement.js +13 -3
- package/lib/cjs/components/Input/Input.js +3 -2
- package/lib/cjs/components/PiaConversation/PiaConversation.js +19 -3
- package/lib/cjs/components/PiaConversation/PiaModal.js +24 -1
- package/lib/cjs/hooks/useReturnFocusToInput.js +28 -0
- package/lib/cjs/stories/assets/storybook-styles.css +0 -135
- package/lib/cjs/utils/contentTransformers.js +52 -6
- package/lib/cjs/version.js +1 -1
- package/lib/mjs/components/Answer/Answer.js +2 -2
- package/lib/mjs/components/CioPia/CioPiaQna.js +12 -2
- package/lib/mjs/components/CioPiaRecs/RecsPodRefinement.js +13 -3
- package/lib/mjs/components/Input/Input.js +3 -2
- package/lib/mjs/components/PiaConversation/PiaConversation.js +19 -3
- package/lib/mjs/components/PiaConversation/PiaModal.js +23 -2
- package/lib/mjs/hooks/useReturnFocusToInput.js +25 -0
- package/lib/mjs/stories/assets/storybook-styles.css +0 -135
- package/lib/mjs/utils/contentTransformers.js +55 -5
- package/lib/mjs/version.js +1 -1
- package/lib/types/components/Input/Input.d.ts +2 -1
- package/lib/types/components/PiaConversation/PiaModal.d.ts +2 -0
- package/lib/types/hooks/useReturnFocusToInput.d.ts +9 -0
- package/lib/types/types.d.ts +5 -0
- package/lib/types/utils/contentTransformers.d.ts +10 -0
- package/lib/types/version.d.ts +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -3,287 +3,26 @@
|
|
|
3
3
|
[](https://www.npmjs.com/package/@constructor-io/constructorio-ui-pia)
|
|
4
4
|
[](https://github.com/Constructor-io/constructorio-ui-pia/blob/main/LICENSE)
|
|
5
5
|
|
|
6
|
-
|
|
6
|
+
React components for [Constructor.io's AI Product Insights Agent](https://constructor.io/): an AI Q&A widget for product pages.
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
**[Documentation →](https://constructor-io.github.io/constructorio-ui-pia/)**
|
|
9
9
|
|
|
10
|
-
|
|
11
|
-
- [Installation](#installation)
|
|
12
|
-
- [Usage](#usage)
|
|
13
|
-
- [Customization](#customization)
|
|
14
|
-
- [Troubleshooting](#troubleshooting)
|
|
15
|
-
- [Local Development](#local-development)
|
|
16
|
-
- [Publishing New Versions](#publishing-new-versions)
|
|
17
|
-
- [Supporting Docs](#supporting-docs)
|
|
18
|
-
- [Related Libraries](#related-libraries)
|
|
19
|
-
- [License](#license)
|
|
20
|
-
|
|
21
|
-
## Overview
|
|
22
|
-
|
|
23
|
-
[Constructor.io's AI Product Insights Agent](https://constructor.io/) is an NLP chatbot embedded in product detail pages, designed to answer key technical product questions essential for final purchase decisions. This UI library simplifies the integration process by providing React components that handle the fetching and rendering logic for the AI Product Insights Agent.
|
|
24
|
-
|
|
25
|
-
[Our Storybook Docs](https://constructor-io.github.io/constructorio-ui-pia/?path=/docs/general-introduction--docs) are the best place to explore the behavior and the available configuration options for this UI library.
|
|
26
|
-
|
|
27
|
-
## Installation
|
|
10
|
+
## Install
|
|
28
11
|
|
|
29
12
|
```bash
|
|
30
13
|
npm i @constructor-io/constructorio-ui-pia
|
|
31
14
|
```
|
|
32
15
|
|
|
33
|
-
### Prerequisites
|
|
34
|
-
|
|
35
|
-
- Node.js >= 20
|
|
36
|
-
- React >= 16.12.0
|
|
37
|
-
- React DOM >= 16.12.0
|
|
38
|
-
|
|
39
16
|
## Usage
|
|
40
17
|
|
|
41
|
-
### Using the React Component
|
|
42
|
-
|
|
43
|
-
The `CioPia` component handles state management, data fetching, and rendering logic for the AI Product Insights Agent.
|
|
44
|
-
|
|
45
18
|
```jsx
|
|
46
|
-
import CioPia from '@constructor-io/constructorio-ui-pia';
|
|
19
|
+
import { CioPia } from '@constructor-io/constructorio-ui-pia';
|
|
47
20
|
import '@constructor-io/constructorio-ui-pia/styles.css';
|
|
48
21
|
|
|
49
|
-
|
|
50
|
-
return <CioPia apiKey='YOUR_API_KEY' itemId='PRODUCT_ITEM_ID' />;
|
|
51
|
-
}
|
|
52
|
-
```
|
|
53
|
-
|
|
54
|
-
#### Display Modes
|
|
55
|
-
|
|
56
|
-
The component supports multiple display modes via the `displayConfigs` prop:
|
|
57
|
-
|
|
58
|
-
```jsx
|
|
59
|
-
// Default inline mode
|
|
60
|
-
<CioPia apiKey='YOUR_API_KEY' itemId='PRODUCT_ITEM_ID' />
|
|
61
|
-
|
|
62
|
-
// Conversation mode with chat history
|
|
63
|
-
<CioPia
|
|
64
|
-
apiKey='YOUR_API_KEY'
|
|
65
|
-
itemId='PRODUCT_ITEM_ID'
|
|
66
|
-
displayConfigs={{ mode: 'conversation' }}
|
|
67
|
-
/>
|
|
68
|
-
|
|
69
|
-
// Modal mode
|
|
70
|
-
<CioPia
|
|
71
|
-
apiKey='YOUR_API_KEY'
|
|
72
|
-
itemId='PRODUCT_ITEM_ID'
|
|
73
|
-
displayConfigs={{ type: 'modal' }}
|
|
74
|
-
/>
|
|
75
|
-
```
|
|
76
|
-
|
|
77
|
-
#### A/B Testing
|
|
78
|
-
|
|
79
|
-
Attach test cells to PIA tracking events, and track the control group without showing the widget:
|
|
80
|
-
|
|
81
|
-
```jsx
|
|
82
|
-
// Test arm: the widget renders, events carry ef-constructorio=variant_a
|
|
83
|
-
<CioPia
|
|
84
|
-
apiKey="key_XXXXXXXX"
|
|
85
|
-
itemId={itemId}
|
|
86
|
-
itemName={itemName}
|
|
87
|
-
abTest={{ testCells: { constructorio: 'variant_a', your_other_test: 'variant_b' }, isControl: false }}
|
|
88
|
-
/>
|
|
89
|
-
|
|
90
|
-
// Control arm: nothing visible renders, but the view event still fires with the control cell
|
|
91
|
-
<CioPia
|
|
92
|
-
apiKey="key_XXXXXXXX"
|
|
93
|
-
itemId={itemId}
|
|
94
|
-
itemName={itemName}
|
|
95
|
-
abTest={{ testCells: { constructorio: 'control' }, isControl: true }}
|
|
96
|
-
/>
|
|
22
|
+
<CioPia apiKey='YOUR_API_KEY' itemId='PRODUCT_ITEM_ID' itemName='Product name' />;
|
|
97
23
|
```
|
|
98
24
|
|
|
99
|
-
|
|
100
|
-
is required.
|
|
101
|
-
|
|
102
|
-
`testCells` is `{ [testName]: cellName }`, and both halves are yours: the keys are your own test
|
|
103
|
-
names, not values Constructor defines. Each entry is sent as its own `ef-<testName>` parameter, so
|
|
104
|
-
a shopper in several concurrent tests carries every cell. Empty or non-string values are dropped,
|
|
105
|
-
so a cell read from a global that resolves to `undefined` is simply not sent.
|
|
106
|
-
|
|
107
|
-
Both arms fire the same `product_insights_agent.view` event through the same viewport tracking,
|
|
108
|
-
so the control group is measured the same way as the test group.
|
|
109
|
-
|
|
110
|
-
If you supply your own `cioClient`, that client owns its own options: set `testCells` there
|
|
111
|
-
instead, as a `ConstructorIOClient` constructor option. `abTest.testCells` is ignored in that
|
|
112
|
-
case, and passing both logs a warning rather than dropping the value silently.
|
|
113
|
-
|
|
114
|
-
`isControl` is required. Stating the arm per shopper is the one thing only you can know, and
|
|
115
|
-
omitting it would quietly put everyone in the test arm with no control group to compare against.
|
|
116
|
-
|
|
117
|
-
#### Configuration Options
|
|
118
|
-
|
|
119
|
-
| Prop | Type | Description |
|
|
120
|
-
| ---------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
121
|
-
| `apiKey` | `string` | Your Constructor.io API key (required) |
|
|
122
|
-
| `itemId` | `string` | The product item ID (required) |
|
|
123
|
-
| `variationId` | `string` | Optional variation ID |
|
|
124
|
-
| `threadId` | `string` | Optional thread ID for conversation context (must be a valid UUID) |
|
|
125
|
-
| `initialConversationHistory` | `ConversationEntry[]` | A conversation you manage, shown before the first question and read once on mount. Conversation and modal modes only (see [Restoring a conversation](#restoring-a-conversation)) |
|
|
126
|
-
| `persistConversation` | `{ enabled: boolean }` | Off by default. Keeps each product's conversation in the browser across page loads. Conversation and modal modes only (see the [Persistent Conversations Guide](https://constructor-io.github.io/constructorio-ui-pia/?path=/docs/general-integration-guide-persistent-conversations-guide--docs)) |
|
|
127
|
-
| `userId` | `string \| null` | Whose persisted conversations these are: the signed-in shopper's id, or `null` for a guest. Change it on login and logout |
|
|
128
|
-
| `displayConfigs` | `object` | Display configuration options (see below) |
|
|
129
|
-
| `trackingConfigs` | `object` | Tracking configuration options (see below) |
|
|
130
|
-
| `callbacks` | `object` | Callback handlers for user interactions |
|
|
131
|
-
| `translations` | `object` | UI string translations for internationalization |
|
|
132
|
-
| `componentOverrides` | `object` | Custom component overrides |
|
|
133
|
-
| `abTest` | `object` | A/B test configuration — test cells for tracking, and a control-group placeholder (see below) |
|
|
134
|
-
|
|
135
|
-
**Display Configs:**
|
|
136
|
-
|
|
137
|
-
| Option | Type | Default | Description |
|
|
138
|
-
| ------------------- | -------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------- |
|
|
139
|
-
| `mode` | `'default' \| 'conversation' \| 'recommendations'` | `'default'` | Display mode. `'recommendations'` is accepted by the type but not yet available — it renders nothing. |
|
|
140
|
-
| `type` | `'inline' \| 'modal'` | `'inline'` | Component type |
|
|
141
|
-
| `showFeedback` | `boolean` | `false` | Show feedback controls on answers |
|
|
142
|
-
| `showPreviousItems` | `boolean` | `true` | Show product carousels from previous conversation entries |
|
|
143
|
-
| `learnMoreUrl` | `string` | - | URL for the "Learn More" disclaimer link |
|
|
144
|
-
|
|
145
|
-
**Tracking Configs:**
|
|
146
|
-
|
|
147
|
-
| Option | Type | Default | Description |
|
|
148
|
-
| --------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
149
|
-
| `viewThreshold` | `number` | `0.5` | Fraction of the container (0–1) that must be visible before the `product_insights_agent.view` event fires. Lower it (e.g. `0.01`) to have the view event fire on minimal visibility. |
|
|
150
|
-
|
|
151
|
-
**AB Test:**
|
|
152
|
-
|
|
153
|
-
| Option | Type | Default | Description |
|
|
154
|
-
| ----------- | ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
155
|
-
| `testCells` | `Record<string, string>` | - | `{ [testName]: cellName }`, each sent as an `ef-<testName>` tracking parameter. Ignored when you supply your own `cioClient`. |
|
|
156
|
-
| `isControl` | `boolean` | required | Renders an invisible, tracking-only placeholder instead of the widget, so the control arm still records a view event. Takes precedence over `displayConfigs.mode`. |
|
|
157
|
-
|
|
158
|
-
**Callbacks:**
|
|
159
|
-
|
|
160
|
-
| Option | Type | Description |
|
|
161
|
-
| -------------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
162
|
-
| `onQuestionSubmit` | `(question: string) => void` | Called when a question is submitted (via Enter key, Send button, or suggested question click) |
|
|
163
|
-
| `onProductCardClick` | `(item: Item) => void` | Called when a product card in the carousel is clicked |
|
|
164
|
-
| `onAddToCart` | `(item: Item, event: React.MouseEvent) => void` | Called when the "Add to Cart" button on a product card is clicked. Passing this callback is what renders the button; without it no cart control is shown |
|
|
165
|
-
| `onFeedback` | `(type: 'up' \| 'down') => void` | Called when the user submits positive or negative feedback on an answer |
|
|
166
|
-
|
|
167
|
-
#### Restoring a conversation
|
|
168
|
-
|
|
169
|
-
`initialConversationHistory` hands the conversation's history to you. Keep it wherever suits you, in the browser or on your own server. In conversation mode `onAnswer` receives the whole history after every answer, so save it per product along with the thread ID and pass both back to pick the conversation up where it left off:
|
|
170
|
-
|
|
171
|
-
```jsx
|
|
172
|
-
function ProductQuestions({ itemId }) {
|
|
173
|
-
// Your own loader: from browser storage, your server, or anywhere else.
|
|
174
|
-
const { isLoading, saved } = useSavedConversation(itemId);
|
|
175
|
-
|
|
176
|
-
// The history is read once, on mount, so wait for it.
|
|
177
|
-
if (isLoading) return null;
|
|
178
|
-
|
|
179
|
-
return (
|
|
180
|
-
<CioPia
|
|
181
|
-
key={itemId}
|
|
182
|
-
apiKey='YOUR_API_KEY'
|
|
183
|
-
itemId={itemId}
|
|
184
|
-
threadId={saved?.threadId}
|
|
185
|
-
initialConversationHistory={saved?.history ?? []}
|
|
186
|
-
displayConfigs={{ mode: 'conversation' }}
|
|
187
|
-
callbacks={{
|
|
188
|
-
onAnswer: (history, context) =>
|
|
189
|
-
saveConversation(context.itemId, { threadId: context.threadId, history }),
|
|
190
|
-
}}
|
|
191
|
-
/>
|
|
192
|
-
);
|
|
193
|
-
}
|
|
194
|
-
```
|
|
195
|
-
|
|
196
|
-
- Passing the prop, even as `[]`, means you manage the history. Pass `[]` when nothing is saved rather than leaving it out.
|
|
197
|
-
- The history is read once, on mount: render `CioPia` after your history has loaded, because a value that arrives later is ignored. Changing `itemId` clears it, so store it per product and remount with `key={itemId}` to load the next product's conversation.
|
|
198
|
-
- Pass the `threadId` the entries came from. The agent keeps the thread's context server-side, so history shown under a different thread is a transcript the agent does not remember.
|
|
199
|
-
- In `type: 'modal'` the entries appear in the dialog, which opens when the shopper asks their next question. Closing the modal clears them, as it does a live conversation.
|
|
200
|
-
- The suggested questions row shows the product's suggested questions, not the follow-ups from the last restored answer.
|
|
201
|
-
- Entries without a string `question` and `answer` are skipped with a console warning, and each entry's `id` is replaced with the widget's own numbering.
|
|
202
|
-
- It is ignored in `mode: 'default'`, which shows only the latest answer, in `mode: 'recommendations'`, and for the A/B control group (`abTest.isControl`).
|
|
203
|
-
|
|
204
|
-
### Using the JavaScript Bundle
|
|
205
|
-
|
|
206
|
-
This is a framework-agnostic method that can be used in any JavaScript project. The `CioPia` function provides a simple interface to inject the PIA component into the provided `selector`.
|
|
207
|
-
|
|
208
|
-
In addition to [PIA component props](https://constructor-io.github.io/constructorio-ui-pia/?path=/docs/components-ciopia--docs), this function also accepts `selector` and `includeCSS`.
|
|
209
|
-
|
|
210
|
-
```js
|
|
211
|
-
import CioPia from '@constructor-io/constructorio-ui-pia/constructorio-ui-pia-bundled';
|
|
212
|
-
|
|
213
|
-
CioPia({
|
|
214
|
-
selector: '#pia-container',
|
|
215
|
-
includeCSS: true, // Include the default CSS styles - defaults to true
|
|
216
|
-
apiKey: 'YOUR_API_KEY',
|
|
217
|
-
itemId: 'PRODUCT_ITEM_ID',
|
|
218
|
-
variationId: 'VARIATION_ID',
|
|
219
|
-
// Optional: provide a thread ID to preserve conversation context (must be a valid UUID)
|
|
220
|
-
threadId: '550e8400-e29b-41d4-a716-446655440000',
|
|
221
|
-
});
|
|
222
|
-
```
|
|
223
|
-
|
|
224
|
-
## Customization
|
|
225
|
-
|
|
226
|
-
### Styling
|
|
227
|
-
|
|
228
|
-
By default, importing React components from this library does not pull any CSS into your project.
|
|
229
|
-
|
|
230
|
-
If you wish to use some starter styles from this library, add an import statement similar to the example below:
|
|
231
|
-
|
|
232
|
-
```js
|
|
233
|
-
import '@constructor-io/constructorio-ui-pia/styles.css';
|
|
234
|
-
```
|
|
235
|
-
|
|
236
|
-
- These starter styles can be used as a foundation to build on top of, or just as a reference for you to replace completely.
|
|
237
|
-
- To opt out of all default styling, do not import the `styles.css` stylesheet.
|
|
238
|
-
- All starter styles in this library are scoped within the `.cio-pia` CSS selector.
|
|
239
|
-
- These starter styles are intended to be extended by layering in your own CSS rules.
|
|
240
|
-
|
|
241
|
-
> Note: When using the JavaScript Bundle, CSS is included by default via the `includeCSS` option (defaults to `true`).
|
|
242
|
-
|
|
243
|
-
### Translations
|
|
244
|
-
|
|
245
|
-
All UI strings can be customized via the `translations` prop for internationalization:
|
|
246
|
-
|
|
247
|
-
```jsx
|
|
248
|
-
<CioPia
|
|
249
|
-
apiKey='YOUR_API_KEY'
|
|
250
|
-
itemId='PRODUCT_ITEM_ID'
|
|
251
|
-
translations={{
|
|
252
|
-
'Any questions about this product?': 'Have a question about this product?',
|
|
253
|
-
'Ask anything': 'Type your question...',
|
|
254
|
-
Send: 'Submit',
|
|
255
|
-
}}
|
|
256
|
-
/>
|
|
257
|
-
```
|
|
258
|
-
|
|
259
|
-
### Component Overrides
|
|
260
|
-
|
|
261
|
-
You can override individual components using the `componentOverrides` prop. See our [Storybook Docs](https://constructor-io.github.io/constructorio-ui-pia/?path=/docs/general-introduction--docs) for available override options.
|
|
262
|
-
|
|
263
|
-
## Troubleshooting
|
|
264
|
-
|
|
265
|
-
### Known Issues
|
|
266
|
-
|
|
267
|
-
**Older JavaScript environments**
|
|
268
|
-
|
|
269
|
-
The library provides two different builds: CommonJS (cjs) and ECMAScript Modules (mjs).
|
|
270
|
-
|
|
271
|
-
For ECMAScript Modules (mjs) build, the JavaScript version is ESNext which might not be supported by your environment. If that's the case and your environment is using an older JavaScript version like ES6 (ES2015), you may get this error:
|
|
272
|
-
|
|
273
|
-
`Module parse failed: Unexpected token (15:32)
|
|
274
|
-
You may need an appropriate loader to handle this file type, currently no loaders are configured to process this file`
|
|
275
|
-
|
|
276
|
-
To solve this you can import the CommonJS (cjs) build which supports ES6 (ES2015) syntax:
|
|
277
|
-
|
|
278
|
-
`import CioPia from '@constructor-io/constructorio-ui-pia/cjs'`
|
|
279
|
-
|
|
280
|
-
**ESLint**
|
|
281
|
-
|
|
282
|
-
There is a known issue with ESLint where it fails to resolve the paths exposed in the `exports` statement of NPM packages. If you are receiving the following error, you can safely disable ESLint using `// eslint-disable-line` for that line.
|
|
283
|
-
|
|
284
|
-
`Unable to resolve path to module '@constructor-io/constructorio-ui-pia/styles.css'`
|
|
285
|
-
|
|
286
|
-
Relevant open issues: [Issue 1868](https://github.com/import-js/eslint-plugin-import/issues/1868), [Issue 1810](https://github.com/import-js/eslint-plugin-import/issues/1810)
|
|
25
|
+
Display modes, callbacks, customization, and every prop are in the [docs](https://constructor-io.github.io/constructorio-ui-pia/).
|
|
287
26
|
|
|
288
27
|
## Local Development
|
|
289
28
|
|
|
@@ -330,11 +69,6 @@ Dispatch the [Deploy Storybook](https://github.com/Constructor-io/constructorio-
|
|
|
330
69
|
|
|
331
70
|
#### Note: This is already done automatically when publishing a new version.
|
|
332
71
|
|
|
333
|
-
## Supporting Docs
|
|
334
|
-
|
|
335
|
-
- [Storybook Docs](https://constructor-io.github.io/constructorio-ui-pia/?path=/docs/general-introduction--docs)
|
|
336
|
-
- [Constructor.io API Documentation](https://docs.constructor.io/)
|
|
337
|
-
|
|
338
72
|
## Related Libraries
|
|
339
73
|
|
|
340
74
|
- [@constructor-io/constructorio-client-javascript](https://github.com/Constructor-io/constructorio-client-javascript) - JavaScript client for Constructor.io API
|
|
@@ -347,7 +81,7 @@ Dispatch the [Deploy Storybook](https://github.com/Constructor-io/constructorio-
|
|
|
347
81
|
1. Fork the repo and create a new branch.
|
|
348
82
|
2. Run `npm ci` to install dependencies.
|
|
349
83
|
3. Make your changes.
|
|
350
|
-
4. Run `npm run lint` and `npm run test` to verify.
|
|
84
|
+
4. Run `npm run lint` and `npm run test` to verify. For docs changes, follow [`.claude/docs.md`](.claude/docs.md).
|
|
351
85
|
5. Submit a PR for review.
|
|
352
86
|
|
|
353
87
|
## License
|