@constructor-io/constructorio-ui-asa 1.0.0

package/lib/types/components/icons/ArrowRightIcon.d.ts

@@ -0,0 +1,2 @@
+import React from 'react';
+export default function ArrowRightIcon(): React.JSX.Element;

package/lib/types/components/icons/ChatBubbleDarkIcon.d.ts

@@ -0,0 +1,2 @@
+import React from 'react';
+export default function ChatBubbleDarkIcon(): React.JSX.Element;

package/lib/types/components/icons/ChatBubbleLightIcon.d.ts

@@ -0,0 +1,2 @@
+import React from 'react';
+export default function ChatBubbleLightIcon(): React.JSX.Element;

package/lib/types/components/icons/SendArrowIcon.d.ts

@@ -0,0 +1,2 @@
+import React from 'react';
+export default function SendArrowIcon(): React.JSX.Element;

package/lib/types/components/icons/SendPlaneIcon.d.ts

@@ -0,0 +1,2 @@
+import React from 'react';
+export default function SendPlaneIcon(): React.JSX.Element;

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

@@ -0,0 +1,5 @@
+export { default as ChatBubbleDarkIcon } from './ChatBubbleDarkIcon';
+export { default as ChatBubbleLightIcon } from './ChatBubbleLightIcon';
+export { default as SendArrowIcon } from './SendArrowIcon';
+export { default as SendPlaneIcon } from './SendPlaneIcon';
+export { default as ArrowRightIcon } from './ArrowRightIcon';

package/lib/types/constants.d.ts

@@ -0,0 +1,2 @@
+export declare const DEMO_API_KEY = "key_fygjntHGW7usvxC8";
+export declare const PLACEHOLDER_IMAGE = "data:image/svg+xml,%3Csvg width='200' height='200' viewBox='0 0 200 200' fill='none' xmlns='http://www.w3.org/2000/svg'%3E%3Crect width='200' height='200' rx='12' fill='%23F3F4F6'/%3E%3Crect x='0.5' y='0.5' width='199' height='199' rx='11.5' stroke='%23E5E7EB'/%3E%3C/svg%3E";

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

@@ -0,0 +1,8 @@
+import { Dispatch, SetStateAction } from 'react';
+import { ResultGroupMeta, ChatMessage } from '../types';
+export type MessageUpdater = Dispatch<SetStateAction<ChatMessage[]>>;
+export declare function handleSearchResult(data: any, pendingGroup: ResultGroupMeta | null, assistantId: string, setMessages: MessageUpdater): ResultGroupMeta | null;
+export declare function handleMessage(data: any, assistantId: string, setMessages: MessageUpdater): void;
+export declare function handleServerError(assistantId: string, setMessages: MessageUpdater): void;
+export declare function handleStreamEnd(assistantId: string, setMessages: MessageUpdater): void;
+export declare function handleStreamError(assistantId: string, setMessages: MessageUpdater): void;

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

@@ -0,0 +1,2 @@
+import { UseChatReturn } from '../types';
+export default function useAsaResults(): UseChatReturn;

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

@@ -0,0 +1,9 @@
+/// <reference types="react" />
+import { AsaContextValue } from '../types';
+export declare const AsaContext: import("react").Context<AsaContextValue | null>;
+/**
+ * React Hook to access state provided by CioAsa provider.
+ * Note: Should only be used by components nested under a CioAsa provider
+ */
+export declare function useCioAsaContext(): AsaContextValue;
+export default useCioAsaContext;

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

@@ -0,0 +1,6 @@
+import ConstructorIOClient from '@constructor-io/constructorio-client-javascript';
+import { Nullable } from '@constructor-io/constructorio-client-javascript/lib/types';
+import type { UseCioClientProps } from '../types';
+type UseCioClient = (props: UseCioClientProps) => Nullable<ConstructorIOClient> | never;
+declare const useCioClient: UseCioClient;
+export default useCioClient;

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

@@ -0,0 +1,11 @@
+import { RefObject } from 'react';
+interface UseFocusTrapOptions {
+    /** Called when the Escape key is pressed while focus is inside the container. */
+    onEscape?: () => void;
+}
+/**
+ * Traps Tab/Shift+Tab focus within the referenced container and invokes
+ * onEscape when Escape is pressed.
+ */
+export default function useFocusTrap(containerRef: RefObject<HTMLElement>, { onEscape }?: UseFocusTrapOptions): void;
+export {};

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

@@ -0,0 +1,15 @@
+import React from 'react';
+interface UseMessageInputOptions {
+    onSend: (text: string) => void;
+    isDisabled?: boolean;
+    /** When true, Shift+Enter will not submit (allowing a newline in multiline inputs). */
+    submitOnEnterOnly?: boolean;
+}
+interface UseMessageInput {
+    value: string;
+    setValue: (value: string) => void;
+    handleSubmit: () => void;
+    handleKeyDown: (e: React.KeyboardEvent) => void;
+}
+export default function useMessageInput({ onSend, isDisabled, submitOnEnterOnly, }: UseMessageInputOptions): UseMessageInput;
+export {};

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

@@ -0,0 +1,7 @@
+import { RequestConfigs } from '../types';
+interface UseRequestConfigsReturn {
+    requestConfigs: RequestConfigs;
+    setRequestConfigs: (configsToUpdate: Partial<RequestConfigs>) => void;
+}
+export default function useRequestConfigs(): UseRequestConfigsReturn;
+export {};

package/lib/types/index.d.ts

@@ -0,0 +1,12 @@
+export { default as CioAsaProvider } from './components/CioAsaProvider/CioAsaProvider';
+export { default as Chat } from './components/Chat/Chat';
+export type { ChatHandle } from './components/Chat/Chat';
+export { default as ResultsBlock } from './components/ResultsBlock/ResultsBlock';
+export type { AspectRatio } from './components/ResultsBlock/ResultsBlock';
+export { default as Button } from './components/Button/Button';
+export type { ButtonProps } from './components/Button/Button';
+export { default as useAsaResults } from './hooks/useAsaResults';
+export { normalizeItemToProduct } from './utils/productNormalizer';
+export type { Product, NormalizeOptions } from './utils/productNormalizer';
+export { ConstructorIOClient } from './types';
+export type { Nullable, CioAsaProviderProps, AsaContextValue, CioClientOptions, RequestConfigs, Formatters, UrlHelpers, QueryParamEncodingOptions, DefaultQueryStringMap, Translations, ChatMessage, ChatMessageStatus, ResultGroup, ResultGroupMeta, UseChatReturn, ChatComponentOverrides, WelcomeScreenOverrides, ChatInputOverrides, AiMessageOverrides, ResultsBlockOverrides, ComponentOverrideProps, IncludeComponentOverrides, ChatHeaderRenderProps, ChatInputRenderProps, WelcomeScreenTitleRenderProps, WelcomeScreenInputRenderProps, SuggestedQuestionsRenderProps, UserMessageRenderProps, AiMessageLoaderRenderProps, AiMessageTextRenderProps, ResultsGroupTitleRenderProps, ResultsViewMoreRenderProps, } from './types';

package/lib/types/types.d.ts

@@ -0,0 +1,178 @@
+import React from 'react';
+import type { ReactNode } from 'react';
+import ConstructorIOClient from '@constructor-io/constructorio-client-javascript';
+import { ConstructorClientOptions, Nullable } from '@constructor-io/constructorio-client-javascript/lib/types';
+import { IAgentParameters } from '@constructor-io/constructorio-client-javascript/lib/types/agent';
+import { ComponentOverrideProps, CarouselOverrides, IncludeComponentOverrides } from '@constructor-io/constructorio-ui-components';
+import type { Product } from './utils/productNormalizer';
+export { Nullable, ConstructorIOClient };
+export type CioClientOptions = Omit<ConstructorClientOptions, 'apiKey' | 'sendTrackingEvents'>;
+export interface PrimaryColorStyles {
+    '--primary-color-h': string;
+    '--primary-color-s': string;
+    '--primary-color-l': string;
+}
+export interface AsaContextValue {
+    cioClient: Nullable<ConstructorIOClient>;
+    cioClientOptions: CioClientOptions;
+    setCioClientOptions: React.Dispatch<CioClientOptions>;
+    staticRequestConfigs: RequestConfigs;
+    formatters: Formatters;
+    urlHelpers: UrlHelpers;
+}
+export interface RequestConfigs extends IAgentParameters {
+    intent?: string;
+}
+export interface Formatters {
+    formatPrice: (price?: number) => string;
+}
+export interface UrlHelpers {
+    getUrl: () => string | undefined;
+    setUrl: (newUrlWithEncodedState: string) => void;
+    getStateFromUrl: (urlString: string) => RequestConfigs;
+    getUrlFromState: (state: RequestConfigs, options: QueryParamEncodingOptions) => string;
+    defaultQueryStringMap: Readonly<DefaultQueryStringMap>;
+}
+export interface CioAsaProviderProps extends Omit<Partial<AsaContextValue>, 'setCioClientOptions' | 'cioClientOptions'> {
+    apiKey?: string;
+}
+export interface UseCioClientProps {
+    apiKey?: string;
+    cioClient?: Nullable<ConstructorIOClient>;
+    cioClientOptions?: CioClientOptions;
+}
+export type DefaultQueryStringMap = {
+    intent: 'q';
+    numResultsPerPage: 'resultsPerPod';
+    filters: 'filters';
+};
+export interface QueryParamEncodingOptions {
+    baseUrl?: string;
+    origin?: string;
+    pathname?: string;
+}
+/**
+ * Composes a type for a Component that accepts
+ * - Props P,
+ * - A children function, that takes RenderProps as its argument
+ */
+export type IncludeRenderProps<ComponentProps, ChildrenFunctionProps> = ComponentProps & {
+    children?: ((props: ChildrenFunctionProps) => ReactNode) | React.ReactNode;
+};
+export interface ChatMessage {
+    id: string;
+    role: 'user' | 'assistant';
+    text: string;
+    groups?: ResultGroup[];
+    status: ChatMessageStatus;
+}
+export type ChatMessageStatus = 'idle' | 'loading' | 'streaming' | 'done' | 'error';
+export interface ResultGroupMeta {
+    display_name: string;
+    value?: string;
+    data?: {
+        display_name?: string;
+        [key: string]: unknown;
+    };
+}
+export interface ResultGroup {
+    group: ResultGroupMeta;
+    searchResults: Record<string, unknown>[];
+}
+export interface UseChatReturn {
+    messages: ChatMessage[];
+    sendMessage: (text: string) => void;
+    isStreaming: boolean;
+    clearHistory: () => void;
+}
+/**
+ * Translations type for internationalizing UI strings.
+ * All keys are optional — any non-provided translation will fall back to the English default.
+ */
+export type Translations = {
+    'CioAsa.header.title'?: string;
+    'CioAsa.header.close'?: string;
+    'CioAsa.input.placeholder'?: string;
+    'CioAsa.input.ariaLabel'?: string;
+    'CioAsa.input.sendAriaLabel'?: string;
+    'CioAsa.welcome.title'?: string;
+    'CioAsa.welcome.placeholder'?: string;
+    'CioAsa.welcome.sendButton'?: string;
+    'CioAsa.welcome.inputAriaLabel'?: string;
+    'CioAsa.welcome.sendAriaLabel'?: string;
+    'CioAsa.welcome.suggestionsAriaLabel'?: string;
+    'CioAsa.messageList.ariaLabel'?: string;
+    'CioAsa.typingIndicator.ariaLabel'?: string;
+    'CioAsa.userMessage.ariaLabel'?: string;
+    'CioAsa.results.viewMore'?: string;
+    'CioAsa.results.addToCart'?: string;
+    'CioAsa.results.saleBadge'?: string;
+    'CioAsa.error.message'?: string;
+};
+export interface ChatHeaderRenderProps {
+    title: string;
+    onClose?: () => void;
+}
+export interface ChatInputRenderProps {
+    value: string;
+    onChange: (value: string) => void;
+    onSubmit: () => void;
+    placeholder: string;
+    isDisabled: boolean;
+}
+export interface WelcomeScreenTitleRenderProps {
+    text: string;
+}
+export interface WelcomeScreenInputRenderProps {
+    value: string;
+    onChange: (value: string) => void;
+    onSubmit: () => void;
+    placeholder: string;
+    isDisabled: boolean;
+}
+export interface SuggestedQuestionsRenderProps {
+    suggestions: string[];
+    onSuggestionClick: (suggestion: string) => void;
+}
+export interface UserMessageRenderProps {
+    text: string;
+}
+export interface AiMessageLoaderRenderProps {
+    translations?: Translations;
+}
+export interface AiMessageTextRenderProps {
+    text: string;
+}
+export interface ResultsGroupTitleRenderProps {
+    label: string;
+}
+export interface ResultsViewMoreRenderProps {
+    group: ResultGroupMeta;
+    onClick: () => void;
+}
+export interface WelcomeScreenOverrides {
+    title?: ComponentOverrideProps<WelcomeScreenTitleRenderProps>;
+    input?: ComponentOverrideProps<WelcomeScreenInputRenderProps>;
+    suggestedQuestions?: ComponentOverrideProps<SuggestedQuestionsRenderProps>;
+}
+export interface ChatInputOverrides {
+    reactNode?: ComponentOverrideProps<ChatInputRenderProps>['reactNode'];
+}
+export interface AiMessageOverrides {
+    loader?: ComponentOverrideProps<AiMessageLoaderRenderProps>;
+    text?: ComponentOverrideProps<AiMessageTextRenderProps>;
+}
+export interface ResultsBlockOverrides {
+    groupTitle?: ComponentOverrideProps<ResultsGroupTitleRenderProps>;
+    viewMore?: ComponentOverrideProps<ResultsViewMoreRenderProps>;
+    carousel?: CarouselOverrides<Product>;
+}
+export interface ChatComponentOverrides {
+    header?: ComponentOverrideProps<ChatHeaderRenderProps>;
+    welcomeScreen?: WelcomeScreenOverrides;
+    input?: ComponentOverrideProps<ChatInputRenderProps>;
+    userMessage?: ComponentOverrideProps<UserMessageRenderProps>;
+    aiMessage?: AiMessageOverrides;
+    resultsBlock?: ResultsBlockOverrides;
+}
+export type { ComponentOverrideProps, IncludeComponentOverrides };

package/lib/types/utils/formatters.d.ts

@@ -0,0 +1 @@
+export declare function formatPrice(price?: number): string;

package/lib/types/utils/productNormalizer.d.ts

@@ -0,0 +1,14 @@
+export interface Product {
+    id: string;
+    name: string;
+    url?: string;
+    imageUrl?: string;
+    price?: string | number;
+    salePrice?: string | number;
+    description?: string;
+    badge?: string;
+}
+export interface NormalizeOptions {
+    saleBadgeText?: string;
+}
+export declare function normalizeItemToProduct(item: any, options?: NormalizeOptions): Product;

package/lib/types/utils/translate.d.ts

@@ -0,0 +1,2 @@
+import type { Translations } from '../types';
+export default function translate(key: keyof Translations, translations?: Translations): string;

package/lib/types/utils/typeHelpers.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Given a Type T and a set of keys K (pipe-delimited string), make those keys optional.
+ */
+export type MakeOptional<Type, Keys extends string & keyof Partial<Type>> = Omit<Type, Keys> & Partial<Pick<Type, Keys>>;

package/lib/types/utils/urlHelpers.d.ts

@@ -0,0 +1,8 @@
+import type { RequestConfigs, QueryParamEncodingOptions, DefaultQueryStringMap } from '../types';
+export declare const defaultQueryStringMap: Readonly<DefaultQueryStringMap>;
+export declare function getUrl(): string | undefined;
+export declare function setUrl(newUrlWithEncodedState: string): void;
+export declare function extractFiltersFromUrl(urlParams: URLSearchParams): {} | undefined;
+export declare function getFilterParamsFromState(urlParams: URLSearchParams, filters: RequestConfigs['filters']): void;
+export declare function getStateFromUrl(url: string): RequestConfigs;
+export declare function getUrlFromState(state: RequestConfigs, options?: QueryParamEncodingOptions): string;

package/lib/types/version.d.ts

@@ -0,0 +1,2 @@
+declare const _default: "1.0.0";
+export default _default;

package/package.json

@@ -0,0 +1,150 @@
+{
+  "name": "@constructor-io/constructorio-ui-asa",
+  "version": "1.0.0",
+  "description": "Constructor.io AI Shopping Agent UI library for web applications",
+  "author": "constructor.io",
+  "license": "MIT",
+  "homepage": "https://github.com/Constructor-io/constructorio-ui-asa#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Constructor-io/constructorio-ui-asa.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Constructor-io/constructorio-ui-asa/issues"
+  },
+  "main": "lib/cjs/index.js",
+  "module": "lib/mjs/index.js",
+  "exports": {
+    ".": {
+      "import": "./lib/mjs/index.js",
+      "require": "./lib/cjs/index.js",
+      "types": "./lib/types/index.d.ts"
+    },
+    "./styles.css": {
+      "import": "./lib/mjs/styles.css",
+      "require": "./lib/cjs/styles.css"
+    },
+    "./components/Chat/styles.css": {
+      "import": "./lib/mjs/components/Chat/Chat.css",
+      "require": "./lib/cjs/components/Chat/Chat.css"
+    },
+    "./components/ResultsBlock/styles.css": {
+      "import": "./lib/mjs/components/ResultsBlock/ResultsBlock.css",
+      "require": "./lib/cjs/components/ResultsBlock/ResultsBlock.css"
+    },
+    "./constructorio-ui-asa-bundled": {
+      "import": "./dist/constructorio-ui-asa-bundled.js",
+      "require": "./dist/constructorio-ui-asa-bundled.js"
+    },
+    "./cjs": {
+      "import": "./lib/cjs/index.js",
+      "require": "./lib/cjs/index.js"
+    }
+  },
+  "files": [
+    "lib/**/*",
+    "dist/constructorio-ui-asa-bundled.js"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "types": "lib/types/index.d.ts",
+  "scripts": {
+    "lint": "eslint src spec --ext js,ts,jsx,tsx",
+    "check-types": "npx tsc --noEmit -p tsconfig.check.json",
+    "copy-styles": "rsync -am --include='*/' --include='*.css' --exclude='*' src/ lib/mjs/ && rsync -am --include='*/' --include='*.css' --exclude='*' src/ lib/cjs/",
+    "dev": "storybook dev -p 6006",
+    "test": "jest",
+    "test:coverage": "jest --coverage",
+    "storybook:ci": "storybook dev --ci --quiet -p 6006",
+    "test-storybook": "test-storybook",
+    "test-storybook:watch": "test-storybook --watch",
+    "test-storybook:ci": "start-server-and-test storybook:ci http://localhost:6006 test-storybook",
+    "build-storybook": "storybook build --docs -o 'docs'",
+    "storybook-docs-dev": "storybook dev --docs -p 6007",
+    "serve-built-storybook": "npx http-server docs",
+    "version": "npm run build-storybook && git add -u ./docs && git add ./docs/* && npm run compile",
+    "compile": "node ./src/generateVersion.js && rm -rf lib && tsc -p tsconfig.json && tsc -p tsconfig-cjs.json && npm run copy-styles && vite build",
+    "check-license": "license-checker --production --onlyAllow 'Apache-2.0;BSD-3-Clause;MIT;0BSD;BSD-2-Clause;ISC' --excludePackages 'picocolors@1.0.0;lightningcss@1.32.0;lightningcss-darwin-arm64@1.32.0;lightningcss-linux-x64-gnu@1.32.0;lightningcss-linux-x64-musl@1.32.0'",
+    "prepare": "husky install"
+  },
+  "peerDependencies": {
+    "@constructor-io/constructorio-client-javascript": "^2.88.0",
+    "@constructor-io/constructorio-ui-components": "^1.6.0",
+    "react": ">=16.12.0",
+    "react-dom": ">=16.12.0",
+    "tslib": "^2.4.0"
+  },
+  "devDependencies": {
+    "@axe-core/react": "^4.7.0",
+    "@constructor-io/constructorio-client-javascript": "^2.88.0",
+    "@constructor-io/constructorio-ui-components": "^1.6.0",
+    "@babel/preset-env": "^7.28.3",
+    "@babel/preset-react": "^7.27.1",
+    "@babel/preset-typescript": "^7.27.1",
+    "@cspell/eslint-plugin": "^6.18.1",
+    "@storybook/addon-a11y": "^8.6.14",
+    "@storybook/addon-actions": "^8.6.14",
+    "@storybook/addon-essentials": "^8.6.14",
+    "@storybook/addon-interactions": "^8.6.14",
+    "@storybook/addon-links": "^8.6.14",
+    "@storybook/addon-mdx-gfm": "^8.6.14",
+    "@storybook/blocks": "^8.6.14",
+    "@storybook/react": "^8.6.14",
+    "@storybook/react-vite": "^8.6.14",
+    "@storybook/react-webpack5": "^8.6.14",
+    "@storybook/test-runner": "^0.22.1",
+    "@storybook/testing-library": "^0.2.0",
+    "@testing-library/jest-dom": "^6.1.5",
+    "@testing-library/react": "^14.0.0",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/jest": "^29.5.8",
+    "@types/jest-axe": "^3.5.9",
+    "@types/react": "^18.0.26",
+    "@types/react-dom": "^18.0.9",
+    "@typescript-eslint/eslint-plugin": "^5.47.0",
+    "@typescript-eslint/parser": "^5.47.0",
+    "chromatic": "^10.0.0",
+    "eslint": "^8.30.0",
+    "eslint-config-airbnb": "^19.0.4",
+    "eslint-config-airbnb-typescript": "^17.0.0",
+    "eslint-config-prettier": "^8.5.0",
+    "eslint-plugin-import": "^2.26.0",
+    "eslint-plugin-jsx-a11y": "^6.7.1",
+    "eslint-plugin-prettier": "^5.0.0",
+    "eslint-plugin-react": "^7.31.11",
+    "eslint-plugin-react-hooks": "^4.6.0",
+    "eslint-plugin-storybook": "^0.6.13",
+    "husky": "^8.0.0",
+    "jest": "^28.1.3",
+    "jest-axe": "^8.0.0",
+    "jest-environment-jsdom": "^30.2.0",
+    "license-checker": "^25.0.1",
+    "prop-types": "^15.8.1",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "start-server-and-test": "^2.0.3",
+    "storybook": "^8.6.17",
+    "typescript": "^4.9.4",
+    "vite": "^6.4.1",
+    "vite-plugin-css-injected-by-js": "^3.1.0",
+    "webpack": "^5.105.4"
+  },
+  "dependencies": {},
+  "overrides": {
+    "brace-expansion@1": "1.1.16",
+    "brace-expansion@2": "2.1.2",
+    "minimatch@9": "9.0.9",
+    "form-data": "4.0.6",
+    "joi": "17.13.4",
+    "js-yaml@3": "3.15.0",
+    "js-yaml@4": "4.3.0",
+    "postcss": "8.5.24",
+    "uuid": "11.1.1",
+    "yaml": "1.10.3"
+  },
+  "volta": {
+    "node": "22.18.0",
+    "npm": "10.9.3"
+  }
+}