@constructor-io/constructorio-ui-agent-overview

v1.0.3

Published

20 days ago

Constructor.io Agent Overview UI library

Constructor.io AI Agent Overview UI Library

A UI library that provides React components to stream and render AI-generated product recommendation sections for Constructor.io's Agent Overview. TypeScript support is available.

Overview

Constructor.io's Agent Overview streams AI-generated product recommendation sections in real time. Given a user intent (e.g. "I want to buy casual shoes"), it presents category suggestions followed by detailed product results. This UI library simplifies the integration process by providing React components and a framework-agnostic standalone bundle that handle the streaming, parsing, and rendering logic.

Our Storybook Docs are the best place to explore the behavior and the available configuration options for this UI library.

Installation

npm i @constructor-io/constructorio-ui-agent-overview

Prerequisites

Node.js >= 20
React >= 16.12.0
React DOM >= 16.12.0

Usage

Using the JavaScript Bundle

This is a framework-agnostic method that can be used in any JavaScript project. The CioAgentOverview function provides a simple interface to inject the Agent Overview component into the provided selector.

import CioAgentOverview from '@constructor-io/constructorio-ui-agent-overview/constructorio-ui-agent-overview-standalone';

CioAgentOverview.init({
  selector: '#agent-overview',
  includeCSS: true, // Include the default CSS styles - defaults to true
  apiKey: 'YOUR_API_KEY',
  intent: 'I want to buy shoes',
  domains: {
    suggestions: 'searchbar',
    results: 'explorer',
  },
});

Using the React Hook

For full control over rendering, use the useAgentOverview hook directly.

import { useAgentOverview, RecommendationSection } from '@constructor-io/constructorio-ui-agent-overview';
import '@constructor-io/constructorio-ui-agent-overview/styles.css';

function MyAgentOverview() {
  const {
    phase,
    categories,
    categoryDescription,
    sections,
    selectCategory,
    isLoading,
    error,
  } = useAgentOverview({
    apiKey: 'YOUR_API_KEY',
    intent: 'I want to buy shoes',
    domains: { suggestions: 'searchbar', results: 'explorer' },
  });

  if (error) return <p>{error}</p>;

  if (phase === 'categories') {
    return (
      <div>
        <p>{categoryDescription}</p>
        {categories.map((category) => (
          <button key={category.title} onClick={() => selectCategory(category)}>
            {category.title}
          </button>
        ))}
      </div>
    );
  }

  return (
    <div>
      {isLoading && <p>Loading...</p>}
      {sections.map((section) => (
        <RecommendationSection key={section.title} section={section} />
      ))}
    </div>
  );
}

Configuration Options

| Prop | Type | Description | |------|------|-------------| | apiKey | string | Your Constructor.io API key (required if cioJsClient is not provided) | | cioJsClient | ConstructorIOClient | Pre-configured Constructor.io JS client instance (takes precedence over apiKey) | | intent | string | The user's search intent that drives agent recommendations (required) | | domains | object | Domain identifiers for category suggestions and product results (required) | | theme | object | Theme overrides for customizing visual appearance via CSS custom properties | | callbacks | object | Callback functions for handling user interactions | | translations | object | Translation overrides for internationalizing UI strings |

Callbacks:

| Option | Type | Description | |--------|------|-------------| | onProductClick | (event, product, section) => void | Called when a user clicks on a product card | | onCategoryClick | (category) => void | Called when a user clicks on a category card | | getProductUrl | (product) => string | Builds a URL for a product card link | | getViewMoreUrl | (section) => string | Builds a "View more" URL from section data |

Customization

Styling

By default, importing React components from this library does not pull any CSS into your project.

If you wish to use some starter styles from this library, add an import statement similar to the example below:

import '@constructor-io/constructorio-ui-agent-overview/styles.css';

These starter styles can be used as a foundation to build on top of, or just as a reference for you to replace completely.
To opt out of all default styling, do not import the styles.css stylesheet.
All starter styles in this library are scoped within the .cio-agent-overview CSS selector.
These starter styles are intended to be extended by layering in your own CSS rules.

Note: When using the JavaScript Bundle, CSS is included by default via the includeCSS option (defaults to true).

Theming

The component supports extensive theming via the theme prop, which maps to CSS custom properties:

<CioAgentOverview
  apiKey='YOUR_API_KEY'
  intent='I want to buy shoes'
  domains={{ suggestions: 'searchbar', results: 'explorer' }}
  theme={{
    primaryColor: '#1a1a1a',
    fontFamily: 'Inter, sans-serif',
    borderColor: '#e0e0e0',
  }}
/>

See our Storybook Docs for the full list of available theme properties.

Translations

All UI strings can be customized via the translations prop for internationalization:

<CioAgentOverview
  apiKey='YOUR_API_KEY'
  intent='I want to buy shoes'
  domains={{ suggestions: 'searchbar', results: 'explorer' }}
  translations={{
    'CioAgentOverview.section.aiBadge': 'AI Powered',
    'CioAgentOverview.categories.viewSuggestions': 'View suggestions',
    'CioAgentOverview.section.viewMore': 'See all',
    'CioAgentOverview.skeleton.thinking': 'Loading...',
    'CioAgentOverview.error.message': 'Something went wrong',
  }}
/>

Troubleshooting

Known Issues

Older JavaScript environments

The library provides two different builds: CommonJS (cjs) and ECMAScript Modules (esm).

For ECMAScript Modules (esm) 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:

Module parse failed: Unexpected token You may need an appropriate loader to handle this file type, currently no loaders are configured to process this file

To solve this you can import the CommonJS (cjs) build which supports ES6 (ES2015) syntax:

import CioAgentOverview from '@constructor-io/constructorio-ui-agent-overview'

(The default import resolves to the CJS build in environments that support require.)

ESLint

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.

Unable to resolve path to module '@constructor-io/constructorio-ui-agent-overview/styles.css'

Relevant open issues: Issue 1868, Issue 1810

Local Development

Development Scripts

npm ci                  # Install dependencies for local dev
npm run storybook       # Start a local dev server for Storybook
npm run lint            # Run lint
npm run test            # Run tests
npm run check-types     # Run TypeScript type checking
npm run test:coverage   # Run tests with coverage report

Library Maintenance

npm run build             # Generate dist folder for publishing to npm
npm run build-storybook   # Generate Storybook static bundle for deploy with GitHub Pages

Publishing New Versions

Dispatch the Publish workflow in GitHub Actions. You're required to provide two arguments:

Version Strategy: major, minor, or patch.
Title: A title for the release.

This workflow will automatically:

Bump the library version using the provided strategy.
Create a new git tag.
Create a new GitHub release.
Compile the library.
Publish the new version to NPM.
Deploy the Storybook docs to GitHub Pages.

Note: Please don't manually increase the package.json version or create new git tags.

The library version is tracked by releases and git tags. We intentionally keep the package.json version at 0.0.0 to avoid pushing changes to the master branch. This solves many security concerns by avoiding the need for branch-protection rule exceptions.

New Storybook Version

Dispatch the Deploy Storybook workflow in GitHub Actions.

Note: This is already done automatically when publishing a new version.

Supporting Docs

Related Libraries

@constructor-io/constructorio-client-javascript - JavaScript client for Constructor.io API
@constructor-io/constructorio-ui-pia - AI Product Insights Agent UI library
@constructor-io/constructorio-ui-autocomplete - Autocomplete UI library
@constructor-io/constructorio-ui-plp - Product Listing Page UI library
@constructor-io/constructorio-ui-quizzes - Quizzes UI library

Contributing

Fork the repo and create a new branch.
Run npm ci to install dependencies.
Make your changes.
Run npm run lint and npm run test to verify.
Submit a PR for review.