@yext/chat-ui-react 0.1.0

package/lib/esm/index.d.ts

@@ -0,0 +1,266 @@
+/// <reference types="react" />
+
+import { JSX as JSX_2 } from 'react/jsx-runtime';
+import { Message } from '@yext/chat-headless-react';
+
+/**
+ * A component that renders the header of a chat bot panel,
+ * including the title and a button to reset the conversation.
+ *
+ * @public
+ *
+ * @param props - {@link ChatHeaderProps}
+ */
+export declare function ChatHeader({ title, showRestartButton, restartButtonIcon, showCloseButton, closeButtonIcon, onClose, customCssClasses, }: ChatHeaderProps): JSX_2.Element;
+
+/**
+ * The CSS class interface for the {@link ChatHeader} component.
+ *
+ * @public
+ */
+export declare interface ChatHeaderCssClasses {
+    header?: string;
+    title?: string;
+    restartButton?: string;
+    closeButton?: string;
+}
+
+/**
+ * The props for the {@link ChatHeader} component.
+ *
+ * @public
+ */
+export declare interface ChatHeaderProps {
+    /**
+     * The headers's title text, essentially how the chat window identifies itself to the user.
+     */
+    title: string;
+    /**
+     * Displays a restart button which allows the user to restart the conversation.
+     * Defaults to false.
+     */
+    showRestartButton?: boolean;
+    /**
+     * Displays a close button which will invoke {@link ChatHeaderProps.onClose} on click.
+     * Default to false.
+     */
+    showCloseButton?: boolean;
+    /** A function which is called when the close button is clicked.  */
+    onClose?: () => void;
+    /**  Custom icon for for restart button. */
+    restartButtonIcon?: JSX.Element;
+    /**  Custom icon for for close button. */
+    closeButtonIcon?: JSX.Element;
+    /**  CSS classes for customizing the component styling. */
+    customCssClasses?: ChatHeaderCssClasses;
+}
+
+/**
+ * A component that allows user to input message and send to Chat API.
+ * @public
+ *
+ * @param props - {@link ChatInputProps}
+ */
+export declare function ChatInput({ placeholder, stream, inputAutoFocus, handleError, sendButtonIcon, customCssClasses, }: ChatInputProps): JSX_2.Element;
+
+/**
+ * The CSS class interface for the {@link ChatInput} component.
+ *
+ * @public
+ */
+export declare interface ChatInputCssClasses {
+    container?: string;
+    textArea?: string;
+    sendButton?: string;
+}
+
+/**
+ * The props for the {@link ChatInput} component.
+ *
+ * @public
+ */
+export declare interface ChatInputProps {
+    /**
+     * The input's placeholder text when no text has been entered by the user.
+     * Defaults to "Type a message...".
+     */
+    placeholder?: string;
+    /**
+     * Enable streaming behavior by making a request to Chat Streaming API.
+     * Defaults to true.
+     */
+    stream?: boolean;
+    /** Enable auto focus for the input box. Defaults to false. */
+    inputAutoFocus?: boolean;
+    /**
+     * A function which is called when an error occurs from
+     * Chat API while processing the user's message.
+     * By default, the error is logged to the console.
+     */
+    handleError?: (e: unknown) => void;
+    /** Custom icon for the send button. */
+    sendButtonIcon?: JSX.Element;
+    /** CSS classes for customizing the component styling. */
+    customCssClasses?: ChatInputCssClasses;
+}
+
+/**
+ * A component that renders a full panel for chat bot interactions. This includes
+ * the message bubbles for the conversation, input box with send button, and header
+ * (if provided).
+ *
+ * @public
+ *
+ * @param props - {@link ChatPanelProps}
+ */
+export declare function ChatPanel(props: ChatPanelProps): JSX_2.Element;
+
+/**
+ * The CSS class interface for the {@link ChatPanel} component.
+ *
+ * @public
+ */
+export declare interface ChatPanelCssClasses {
+    container?: string;
+    messagesContainer?: string;
+    inputContainer?: string;
+    inputCssClasses?: ChatInputCssClasses;
+    messageBubbleCssClasses?: MessageBubbleCssClasses;
+}
+
+/**
+ * The props for the {@link ChatPanel} component.
+ *
+ * @public
+ */
+export declare interface ChatPanelProps extends Omit<MessageBubbleProps, "customCssClasses" | "message">, Omit<ChatInputProps, "customCssClasses"> {
+    /** A header to render at the top of the panel. */
+    header?: JSX.Element;
+    /**
+     * CSS classes for customizing the component styling.
+     */
+    customCssClasses?: ChatPanelCssClasses;
+}
+
+/**
+ * A component that renders a popup button that displays and hides
+ * a panel for chat bot interactions.
+ *
+ * @public
+ *
+ * @param props - {@link ChatPanelProps}
+ */
+export declare function ChatPopUp(props: ChatPopUpProps): JSX_2.Element;
+
+/**
+ * The CSS class interface for the {@link ChatPopUp} component.
+ *
+ * @public
+ */
+export declare interface ChatPopUpCssClasses {
+    container?: string;
+    panel?: string;
+    panel__display?: string;
+    panel__hidden?: string;
+    button?: string;
+    button__display?: string;
+    button__hidden?: string;
+    headerCssClasses?: ChatHeaderCssClasses;
+    panelCssClasses?: ChatPanelCssClasses;
+}
+
+/**
+ * The props for the {@link ChatPopUp} component.
+ *
+ * @public
+ */
+export declare interface ChatPopUpProps extends Omit<ChatHeaderProps, "showCloseButton" | "customCssClasses">, Omit<ChatPanelProps, "header" | "customCssClasses"> {
+    /** Custom icon for the popup button to open the panel. */
+    openPanelButtonIcon?: JSX.Element;
+    /**
+     * CSS classes for customizing the component styling.
+     */
+    customCssClasses?: ChatPopUpCssClasses;
+}
+
+/**
+ * A component that displays the provided message.
+ *
+ * @public
+ *
+ * @param props - {@link MessageBubbleProps}
+ */
+export declare function MessageBubble({ message, showTimestamp, customCssClasses, formatTimestamp, }: MessageBubbleProps): JSX_2.Element;
+
+/**
+ * The CSS class interface for the {@link MessageBubble} component.
+ *
+ * @public
+ */
+export declare interface MessageBubbleCssClasses {
+    topContainer?: string;
+    subContainer?: string;
+    subContainer__bot?: string;
+    subContainer__user?: string;
+    message?: string;
+    message__bot?: string;
+    message__user?: string;
+    timestamp?: string;
+    timestamp__bot?: string;
+    timestamp__user?: string;
+}
+
+/**
+ * The props for the {@link MessageBubble} component.
+ *
+ * @public
+ */
+export declare interface MessageBubbleProps {
+    /** The message to display. */
+    message: Message;
+    /**
+     * Whether to show the timestamp of the message with the message bubble.
+     * Defaults to true.
+     */
+    showTimestamp?: boolean;
+    /**
+     * A function which is called to format the message's timestamp given in
+     * ISO format (e.g. "2023-05-18T19:33:34.553Z").
+     * Defaults to "HH:MM:SS A" (e.g. "7:33:34 PM").
+     */
+    formatTimestamp?: (timestamp: string) => string;
+    /** CSS classes for customizing the component styling. */
+    customCssClasses?: MessageBubbleCssClasses;
+}
+
+/**
+ * useComposedCssClasses merges a component's built-in tailwind classes with custom tailwind classes.
+ *
+ * @remarks
+ * Tailwind classes will be merged without conflict, with custom classes having higher priority
+ * than built-in ones.
+ *
+ * @example
+ * Suppose a component has built-in classes of `{ container: 'px-4 text-slate-700' }`.
+ *
+ * Passing in the custom classes:
+ *
+ * ```ts
+ * { container: 'text-red-200 mb-3' }
+ * ```
+ *
+ * results in the merged classes of:
+ *
+ * ```ts
+ * { container: 'px-4 text-red-200 mb-3' }
+ * ```
+ *
+ * @public
+ *
+ * @param builtInClasses - The component's built-in tailwind classes
+ * @param customClasses - The custom tailwind classes to merge with the built-in ones
+ * @returns The composed CSS classes
+ */
+export declare function useComposedCssClasses<ClassInterface extends Partial<Record<keyof ClassInterface, string | object>>>(builtInClasses: Readonly<ClassInterface>, customClasses?: Partial<ClassInterface>): ClassInterface;
+
+export { }

package/lib/esm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,SAAS,CAAC"}

package/lib/esm/index.js

@@ -0,0 +1,3 @@
+export * from "./components";
+export * from "./hooks";
+//# sourceMappingURL=index.js.map

package/lib/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,SAAS,CAAC"}

package/lib/esm/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.35.1"
+    }
+  ]
+}

package/lib/esm/utils/defaultHandleError.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Default handler function for API errors.
+ *
+ * @internal
+ *
+ * @param e - error returned from api request
+ */
+export declare function defaultHandleApiError(e: unknown): void;
+//# sourceMappingURL=defaultHandleError.d.ts.map

package/lib/esm/utils/defaultHandleError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaultHandleError.d.ts","sourceRoot":"","sources":["../../../src/utils/defaultHandleError.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,OAAO,QAE/C"}

package/lib/esm/utils/defaultHandleError.js

@@ -0,0 +1,11 @@
+/**
+ * Default handler function for API errors.
+ *
+ * @internal
+ *
+ * @param e - error returned from api request
+ */
+export function defaultHandleApiError(e) {
+    console.error(e);
+}
+//# sourceMappingURL=defaultHandleError.js.map

package/lib/esm/utils/defaultHandleError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaultHandleError.js","sourceRoot":"","sources":["../../../src/utils/defaultHandleError.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,CAAU;IAC9C,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACnB,CAAC"}

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "@yext/chat-ui-react",
+  "version": "0.1.0",
+  "description": "A library of React Components for powering Yext Chat integrations.",
+  "author": "clippy@yext.com",
+  "main": "./lib/commonjs/index.js",
+  "module": "./lib/esm/index.js",
+  "types": "./lib/esm/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": "./lib/esm/index.js",
+      "require": "./lib/commonjs/index.js"
+    },
+    "./bundle.css": "./lib/bundle.css"
+  },
+  "license": "BSD-3-Clause",
+  "files": [
+    "lib",
+    "src",
+    "THIRD-PARTY-NOTICES",
+    "LICENSE"
+  ],
+  "keywords": [
+    "chat",
+    "ai",
+    "yext",
+    "react",
+    "components",
+    "tailwindcss"
+  ],
+  "scripts": {
+    "lint": "prettier --write . && eslint --fix --max-warnings=0 .",
+    "test": "jest --config=jest.config.json",
+    "storybook": "storybook dev -p 6006",
+    "dev": "tsc --watch -p tsconfig.esm.json",
+    "generate-docs": "api-extractor run --local --verbose && api-documenter markdown --input-folder temp --output-folder docs && rm -rf temp",
+    "generate-notices": "generate-license-file --input package.json --output ./THIRD-PARTY-NOTICES --overwrite",
+    "build:js": "tsc -p tsconfig.esm.json && tsc -p tsconfig.cjs.json",
+    "build:css": "tailwindcss -o ./lib/bundle.css --minify -c tailwind.config.js",
+    "build": "rm -rf lib/** && npm run build:js && npm run build:css && npm run generate-docs && npm run generate-notices",
+    "build-storybook": "storybook build"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.21.8",
+    "@babel/preset-env": "^7.21.5",
+    "@babel/preset-react": "^7.18.6",
+    "@babel/preset-typescript": "^7.21.5",
+    "@microsoft/api-documenter": "^7.22.8",
+    "@microsoft/api-extractor": "^7.35.1",
+    "@storybook/addon-essentials": "^7.0.18",
+    "@storybook/addon-interactions": "^7.0.18",
+    "@storybook/addon-links": "^7.0.18",
+    "@storybook/blocks": "^7.0.18",
+    "@storybook/react": "^7.0.17",
+    "@storybook/react-vite": "^7.0.17",
+    "@storybook/testing-library": "^0.1.0",
+    "@tailwindcss/container-queries": "^0.1.1",
+    "@tailwindcss/typography": "^0.5.9",
+    "@testing-library/jest-dom": "^5.16.5",
+    "@testing-library/react": "^14.0.0",
+    "@testing-library/user-event": "^14.4.3",
+    "@types/jest": "^29.5.1",
+    "@types/react": "^18.2.7",
+    "@yext/eslint-config": "^1.0.0",
+    "babel-jest": "^29.5.0",
+    "eslint": "^8.39.0",
+    "eslint-plugin-storybook": "^0.6.12",
+    "generate-license-file": "^2.0.0",
+    "jest": "^29.5.0",
+    "jest-environment-jsdom": "^29.5.0",
+    "msw": "^1.2.1",
+    "msw-storybook-addon": "^1.8.0",
+    "prettier": "^2.8.8",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "storybook": "^7.0.17",
+    "tailwindcss": "^3.3.2",
+    "typescript": "^5.0.4"
+  },
+  "peerDependencies": {
+    "@yext/chat-headless-react": "^0.3.1",
+    "react": "^16.14 || ^17 || ^18",
+    "react-dom": "^16.14 || ^17 || || ^18"
+  },
+  "dependencies": {
+    "react-expanding-textarea": "^2.3.6",
+    "react-markdown": "^6.0.3",
+    "react-textarea-autosize": "^8.4.1",
+    "rehype-raw": "^5.0.0",
+    "rehype-sanitize": "^4.0.0",
+    "remark-gfm": "^1.0.0",
+    "tailwind-merge": "^1.12.0"
+  }
+}

package/src/components/ChatHeader.tsx

@@ -0,0 +1,118 @@
+import { useChatActions } from "@yext/chat-headless-react";
+import { DualSyncIcon } from "../icons/DualSync"
+import { useComposedCssClasses } from "../hooks/useComposedCssClasses";
+import { useCallback, useRef, useState } from "react";
+import { twMerge } from "tailwind-merge";
+import { CrossIcon } from "../icons/Cross";
+
+/**
+ * The CSS class interface for the {@link ChatHeader} component.
+ *
+ * @public
+ */
+export interface ChatHeaderCssClasses {
+  header?: string;
+  title?: string;
+  restartButton?: string;
+  closeButton?: string;
+}
+
+const builtInCssClasses: Readonly<ChatHeaderCssClasses> = {
+  header:
+    "w-full px-4 py-3 flex justify-between bg-gradient-to-tr from-blue-600 to-blue-800 rounded-t-3xl",
+  title: "text-white text-xl font-medium",
+  restartButton: "w-8 text-white stroke-[0.2] ml-auto",
+  closeButton: "w-8 text-white hover:scale-110"
+};
+
+/**
+ * The props for the {@link ChatHeader} component.
+ *
+ * @public
+ */
+export interface ChatHeaderProps {
+  /**
+   * The headers's title text, essentially how the chat window identifies itself to the user.
+   */
+  title: string;
+  /**
+   * Displays a restart button which allows the user to restart the conversation.
+   * Defaults to false.
+   */
+  showRestartButton?: boolean;
+  /**
+   * Displays a close button which will invoke {@link ChatHeaderProps.onClose} on click.
+   * Default to false.
+   */
+  showCloseButton?: boolean;
+  /** A function which is called when the close button is clicked.  */
+  onClose?: () => void;
+  /**  Custom icon for for restart button. */
+  restartButtonIcon?: JSX.Element;
+  /**  Custom icon for for close button. */
+  closeButtonIcon?: JSX.Element;
+  /**  CSS classes for customizing the component styling. */
+  customCssClasses?: ChatHeaderCssClasses;
+}
+
+/**
+ * A component that renders the header of a chat bot panel,
+ * including the title and a button to reset the conversation.
+ *
+ * @public
+ *
+ * @param props - {@link ChatHeaderProps}
+ */
+export function ChatHeader({
+  title,
+  showRestartButton,
+  restartButtonIcon = <DualSyncIcon />,
+  showCloseButton,
+  closeButtonIcon = <CrossIcon />,
+  onClose,
+  customCssClasses,
+}: ChatHeaderProps) {
+  const chat = useChatActions();
+
+  const cssClasses = useComposedCssClasses(builtInCssClasses, customCssClasses);
+
+  const [isSpinning, setIsSpinning] = useState(false);
+  const restartButtonCssClasses = twMerge(
+    cssClasses.restartButton,
+    isSpinning ? "animate-[spin_0.3s_linear_infinite]" : "hover:scale-110"
+  );
+
+  const clearTimerRef = useRef<ReturnType<typeof setTimeout>>();
+  const onRestart = useCallback(async () => {
+    clearTimeout(clearTimerRef.current);
+    setIsSpinning(true);
+    clearTimerRef.current = setTimeout(() => {
+      setIsSpinning(false);
+    }, 1000);
+    chat.restartConversation();
+  }, [chat]);
+
+  return (
+    <div className={cssClasses.header}>
+      <h1 className={cssClasses.title}>{title}</h1>
+      {showRestartButton && (
+        <button
+          aria-label="Restart Conversation"
+          onClick={onRestart}
+          className={restartButtonCssClasses}
+        >
+          {restartButtonIcon}
+        </button>
+      )}
+      {showCloseButton && (
+        <button
+        aria-label="Close Chat"
+        onClick={onClose}
+        className={cssClasses.closeButton}
+      >
+        {closeButtonIcon}
+      </button>
+      )}
+    </div>
+  );
+}

package/src/components/ChatInput.tsx

@@ -0,0 +1,129 @@
+import { useCallback, useState } from "react";
+import { useChatActions, useChatState } from "@yext/chat-headless-react";
+import { ArrowIcon } from "../icons/Arrow";
+import { useComposedCssClasses } from "../hooks";
+import Textarea from "react-expanding-textarea";
+import { twMerge } from "tailwind-merge";
+import { defaultHandleApiError } from "../utils/defaultHandleError";
+
+/**
+ * The CSS class interface for the {@link ChatInput} component.
+ *
+ * @public
+ */
+export interface ChatInputCssClasses {
+  container?: string;
+  textArea?: string;
+  sendButton?: string;
+}
+
+const builtInCssClasses: ChatInputCssClasses = {
+  container: "w-full h-fit flex flex-row relative @container",
+  textArea:
+    "w-full p-4 pr-10 border border-slate-300 disabled:bg-slate-50 rounded-3xl resize-none text-[13px] @[480px]:text-base",
+  sendButton:
+    "rounded-full p-1.5 w-8 stroke-2 text-white bg-blue-600 disabled:bg-slate-100 hover:bg-blue-800 active:scale-90 transition-all absolute right-7 bottom-2.5 @[480px]:bottom-3.5",
+};
+
+/**
+ * The props for the {@link ChatInput} component.
+ *
+ * @public
+ */
+export interface ChatInputProps {
+  /**
+   * The input's placeholder text when no text has been entered by the user.
+   * Defaults to "Type a message...".
+   */
+  placeholder?: string;
+  /**
+   * Enable streaming behavior by making a request to Chat Streaming API.
+   * Defaults to true.
+   */
+  stream?: boolean;
+  /** Enable auto focus for the input box. Defaults to false. */
+  inputAutoFocus?: boolean;
+  /**
+   * A function which is called when an error occurs from
+   * Chat API while processing the user's message.
+   * By default, the error is logged to the console.
+   */
+  handleError?: (e: unknown) => void;
+  /** Custom icon for the send button. */
+  sendButtonIcon?: JSX.Element;
+  /** CSS classes for customizing the component styling. */
+  customCssClasses?: ChatInputCssClasses;
+}
+
+/**
+ * A component that allows user to input message and send to Chat API.
+ * @public
+ *
+ * @param props - {@link ChatInputProps}
+ */
+export function ChatInput({
+  placeholder = "Type a message...",
+  stream = true,
+  inputAutoFocus = false,
+  handleError,
+  sendButtonIcon = <ArrowIcon />,
+  customCssClasses,
+}: ChatInputProps) {
+  const chat = useChatActions();
+  const [input, setInput] = useState("");
+  const canSendMessage = useChatState(
+    (state) => state.conversation.canSendMessage
+  );
+
+  const cssClasses = useComposedCssClasses(builtInCssClasses, customCssClasses);
+  const sendButtonClassNames = twMerge(
+    cssClasses.sendButton,
+    input.length === 0 && "opacity-0 invisible"
+  );
+
+  const sendMessage = useCallback(async () => {
+    const res = stream
+      ? chat.streamNextMessage(input)
+      : chat.getNextMessage(input);
+    setInput("");
+    res.catch((e) => (handleError ? handleError(e) : defaultHandleApiError(e)));
+  }, [chat, input, handleError, stream]);
+
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
+      if (e.key === "Enter") {
+        sendMessage();
+      }
+    },
+    [sendMessage]
+  );
+
+  const onInputChange = useCallback(
+    (e: React.ChangeEvent<HTMLTextAreaElement>) => {
+      setInput(e.target.value);
+    },
+    []
+  );
+
+  return (
+    <div className={cssClasses.container}>
+      <Textarea
+        autoFocus={inputAutoFocus}
+        disabled={!canSendMessage}
+        onKeyDown={handleKeyDown}
+        value={input}
+        onChange={onInputChange}
+        className={cssClasses.textArea}
+        placeholder={placeholder}
+      />
+      <button
+        aria-label="Send Message"
+        disabled={!canSendMessage}
+        onClick={sendMessage}
+        className={sendButtonClassNames}
+      >
+        {sendButtonIcon}
+      </button>
+    </div>
+  );
+}