feat(chat): add greeting screen component

bundlesize.config.json

@@ -10,11 +10,11 @@
     },
     {
       "path": "./packages/instantsearch.js/dist/instantsearch.production.min.js",
-      "maxSize": "122 kB"
+      "maxSize": "122.5 kB"
     },
     {
       "path": "./packages/instantsearch.js/dist/instantsearch.development.js",
-      "maxSize": "253.4 kB"
+      "maxSize": "254 kB"
     },
     {
       "path": "packages/react-instantsearch-core/dist/umd/ReactInstantSearchCore.min.js",
@@ -62,7 +62,7 @@
     },
     {
       "path": "./packages/instantsearch.css/themes/nova-min.css",
-      "maxSize": "9.75 kB"
+      "maxSize": "10 kB"
     },
     {
       "path": "./packages/instantsearch.css/themes/satellite.css",

examples/js/getting-started/src/app.css

@@ -163,3 +163,8 @@
     rgba(255, 255, 255, 1) 100%
   );
 }
+
+.ais-ChatGreeting-banner {
+  width: 3rem;
+  height: 3rem;
+}

examples/js/getting-started/src/app.js

@@ -1,6 +1,6 @@
 import { liteClient as algoliasearch } from 'algoliasearch/lite';
 import instantsearch from 'instantsearch.js';
-import { carousel } from 'instantsearch.js/es/templates';
+import { carousel, chatGreeting } from 'instantsearch.js/es/templates';
 import {
   configure,
   hits,
@@ -14,6 +14,7 @@ import {
   currentRefinements,
 } from 'instantsearch.js/es/widgets';
 
+import sparklesIcon from './sparkles.svg';
 import 'instantsearch.css/themes/satellite.css';
 
 const searchClient = algoliasearch(
@@ -111,6 +112,13 @@ search.addWidgets([
     agentId: 'eedef238-5468-470d-bc37-f99fa741bd25',
     templates: {
       item: productItemTemplate,
+      empty: chatGreeting({
+        banner: sparklesIcon,
+        translations: {
+          heading: 'Welcome! How can I help?',
+          subheading: 'Ask me anything about our products.',
+        },
+      }),
     },
   }),
 ]);

examples/react/getting-started/src/App.css

@@ -170,3 +170,8 @@ em {
     rgba(255, 255, 255, 1) 100%
   );
 }
+
+.ais-ChatGreeting-banner {
+  width: 3rem;
+  height: 3rem;
+}

examples/react/getting-started/src/App.tsx

@@ -12,14 +12,14 @@ import {
   TrendingItems,
   Carousel,
   Chat,
+  ChatGreeting,
   FilterSuggestions,
   CurrentRefinements,
 } from 'react-instantsearch';
 
 import { Panel } from './Panel';
-
 import 'instantsearch.css/themes/satellite.css';
-
+import sparklesIcon from './sparkles.svg';
 import './App.css';
 
 const searchClient = algoliasearch(
@@ -95,6 +95,16 @@ export function App() {
             agentId="eedef238-5468-470d-bc37-f99fa741bd25"
             feedback={true}
             itemComponent={ItemComponent}
+            emptyComponent={(props) => (
+              <ChatGreeting
+                {...props}
+                banner={sparklesIcon as unknown as string}
+                translations={{
+                  heading: 'Welcome! How can I help?',
+                  subheading: 'Ask me anything about our products.',
+                }}
+              />
+            )}
           />
         </InstantSearch>
       </div>

packages/instantsearch-ui-components/src/components/chat/ChatGreeting.tsx

@@ -0,0 +1,97 @@
+/** @jsx createElement */
+
+import { cx } from '../../lib';
+
+import type { ComponentProps, Renderer } from '../../types';
+import type { ChatEmptyProps } from './types';
+
+export type ChatGreetingTranslations = {
+  /**
+   * Heading text for the empty screen
+   */
+  heading: string;
+  /**
+   * Subheading text for the empty screen
+   */
+  subheading: string;
+};
+
+export type ChatGreetingClassNames = {
+  /**
+   * Class names to apply to the root element
+   */
+  root?: string | string[];
+  /**
+   * Class names to apply to the heading element
+   */
+  heading?: string | string[];
+  /**
+   * Class names to apply to the subheading element
+   */
+  subheading?: string | string[];
+  /**
+   * Class names to apply to the banner element
+   */
+  banner?: string | string[];
+};
+
+export type ChatGreetingProps = ChatEmptyProps & ComponentProps<'div'> & {
+  /**
+   * Optional translations
+   */
+  translations?: Partial<ChatGreetingTranslations>;
+  /**
+   * Optional class names
+   */
+  classNames?: ChatGreetingClassNames;
+  /**
+   * Optional banner image URL
+   */
+  banner?: string;
+};
+
+export function createChatGreetingComponent({
+  createElement,
+}: Pick<Renderer, 'createElement'>) {
+  return function ChatGreeting(userProps: ChatGreetingProps) {
+    const {
+      translations: userTranslations,
+      classNames = {},
+      sendMessage: _sendMessage,
+      status: _status,
+      onClose: _onClose,
+      setInput: _setInput,
+      banner,
+      ...props
+    } = userProps;
+    const translations: Required<ChatGreetingTranslations> = {
+      heading:
+        userTranslations?.heading ??
+        'How can I help you today?',
+      subheading:
+        userTranslations?.subheading ??
+        "Ask me anything about our products, and I'll do my best to assist you.",
+    };
+
+    return (
+      <div
+        {...props}
+        className={cx('ais-ChatGreeting', classNames.root, props.className)}
+      >
+        {banner && (
+          <img
+            className={cx('ais-ChatGreeting-banner', classNames.banner)}
+            src={banner}
+            alt=""
+          />
+        )}
+        <h2 className={cx('ais-ChatGreeting-heading', classNames.heading)}>
+          {translations.heading}
+        </h2>
+        <p className={cx('ais-ChatGreeting-subheading', classNames.subheading)}>
+          {translations.subheading}
+        </p>
+      </div>
+    );
+  };
+}

packages/instantsearch-ui-components/src/components/chat/ChatMessages.tsx

@@ -30,7 +30,7 @@ import type {
 } from './ChatMessage';
 import type { ChatMessageErrorProps } from './ChatMessageError';
 import type { ChatMessageLoaderProps } from './ChatMessageLoader';
-import type { ChatMessageBase, ChatStatus, ClientSideTools } from './types';
+import type { ChatEmptyProps, ChatLayoutOwnProps, ChatMessageBase, ChatStatus, ClientSideTools } from './types';
 
 export type ChatMessagesTranslations = {
   /**
@@ -109,6 +109,10 @@ export type ChatMessagesProps<
    * Custom error component
    */
   errorComponent?: (props: ChatMessageErrorProps) => JSX.Element;
+  /**
+   * Custom empty component shown when there are no messages
+   */
+  emptyComponent?: (props: ChatEmptyProps) => JSX.Element;
   /**
    * Custom actions component
    */
@@ -141,6 +145,14 @@ export type ChatMessagesProps<
    * Function to close the chat
    */
   onClose: () => void;
+  /**
+   * Function to send a message to the chat
+   */
+  sendMessage?: ChatLayoutOwnProps['sendMessage'];
+  /**
+   * Function to set the prompt input value
+   */
+  setInput?: (input: string) => void;
   /**
    * Optional class names
    */
@@ -361,6 +373,7 @@ export function createChatMessagesComponent({
       messageComponent: MessageComponent,
       loaderComponent: LoaderComponent,
       errorComponent: ErrorComponent,
+      emptyComponent: EmptyComponent,
       actionsComponent: ActionsComponent,
       tools,
       indexUiState,
@@ -369,6 +382,8 @@ export function createChatMessagesComponent({
       hideScrollToBottom = false,
       onReload,
       onClose,
+      sendMessage,
+      setInput,
       translations: userTranslations,
       userMessageProps,
       assistantMessageProps,
@@ -421,6 +436,9 @@ export function createChatMessagesComponent({
       isStreamingWithNoContent ||
       isStreamingNonTextContent;
 
+    const showEmpty =
+      messages.length === 0 && !showLoader && !isClearing && status !== 'error';
+
     const DefaultMessage = MessageComponent || DefaultMessageComponent;
     const DefaultLoader = LoaderComponent || DefaultLoaderComponent;
     const DefaultError = ErrorComponent || DefaultErrorComponent;
@@ -449,6 +467,15 @@ export function createChatMessagesComponent({
               }
             }}
           >
+            {showEmpty && EmptyComponent && (
+              <EmptyComponent
+                sendMessage={sendMessage}
+                setInput={setInput}
+                status={status}
+                onClose={onClose}
+              />
+            )}
+
             {messages.map((message, index) => (
               <DefaultMessage
                 key={message.id}

packages/instantsearch-ui-components/src/components/chat/types.ts

@@ -512,3 +512,23 @@ export type UserClientSideTool = Omit<
   'addToolResult' | 'applyFilters' | 'sendEvent'
 >;
 export type UserClientSideTools = Record<string, UserClientSideTool>;
+
+export type ChatEmptyProps = {
+  /**
+   * Function to send a message to the chat
+   */
+  sendMessage?: ChatLayoutOwnProps['sendMessage'];
+  /**
+   * Current chat status
+   */
+  status?: ChatStatus;
+  /**
+   * Callback to close the chat
+   */
+  onClose?: () => void;
+  /**
+   * Function to set the prompt input value
+   */
+  setInput?: (input: string) => void;
+};
+

packages/instantsearch-ui-components/src/components/index.ts

@@ -10,6 +10,7 @@ export * from './chat/ChatMessage';
 export * from './chat/ChatMessages';
 export * from './chat/ChatMessageLoader';
 export * from './chat/ChatMessageError';
+export * from './chat/ChatGreeting';
 export * from './chat/ChatPrompt';
 export * from './chat/ChatPromptSuggestions';
 export * from './chat/ChatToggleButton';

packages/instantsearch.css/src/components/chat.scss

@@ -11,6 +11,7 @@
 @use 'chat/chat-messages';
 @use 'chat/chat-message';
 @use 'chat/chat-message-loader';
+@use 'chat/chat-greeting';
 @use 'chat/chat-prompt';
 @use 'chat/chat-carousel';
 @use 'chat/chat-suggestions';

packages/instantsearch.css/src/components/chat/_chat-greeting.scss

@@ -0,0 +1,28 @@
+.ais-ChatGreeting {
+  --ais-chat-greeting-padding: 0.5rem;
+
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  padding: var(--ais-chat-greeting-padding);
+  flex: 1;
+  gap: calc(var(--ais-spacing) * 0.5);
+}
+
+.ais-ChatGreeting-heading {
+  font-size: 1.25em;
+  font-weight: 700;
+  margin: 0;
+}
+
+.ais-ChatGreeting-subheading {
+  font-size: 0.875em;
+  opacity: 0.7;
+  margin: 0;
+  line-height: 1.5;
+}
+
+.ais-ChatGreeting-banner {
+  max-width: 100%;
+  height: auto;
+}

packages/instantsearch.js/src/templates/chat-greeting/chat-greeting.tsx

@@ -0,0 +1,18 @@
+/** @jsx h */
+
+import { createChatGreetingComponent } from 'instantsearch-ui-components';
+import { h } from 'preact';
+
+import type { ChatGreetingProps } from 'instantsearch-ui-components';
+
+const ChatGreetingComponent = createChatGreetingComponent({
+  createElement: h,
+});
+
+export function chatGreeting(
+  options?: Pick<ChatGreetingProps, 'banner' | 'translations' | 'classNames'>
+) {
+  return function ChatGreetingTemplate(props: ChatGreetingProps) {
+    return <ChatGreetingComponent {...props} {...options} />;
+  };
+}

packages/instantsearch.js/src/templates/index.ts

@@ -2,3 +2,4 @@ export * from './carousel/carousel';
 export * from './chat-layout/chat-overlay-layout';
 export * from './chat-layout/chat-inline-layout';
 export * from './chat-layout/chat-sidepanel-layout';
+export * from './chat-greeting/chat-greeting';