feat(promptSuggestions): add prompt suggestions widget

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

@@ -0,0 +1,132 @@
+/** @jsx createElement */
+import { cx } from '../../lib';
+import { createButtonComponent } from '../Button';
+
+import type { Renderer } from '../../types';
+import type { ChatStatus } from './types';
+
+export type PromptSuggestionsClassNames = {
+  /**
+   * Class name for the root element
+   */
+  root?: string;
+  /**
+   * Class name for the header element
+   */
+  header?: string;
+  /**
+   * Class name for the suggestions list
+   */
+  suggestionsList?: string;
+  /**
+   * Class name for each suggestion item
+   */
+  suggestionItem?: string;
+  /**
+   * Class name for the loading state
+   */
+  loading?: string;
+};
+
+export type PromptSuggestionsTranslations = {
+  /**
+   * Text for the suggestions header
+   */
+  suggestionsHeaderText?: string;
+};
+
+export type PromptSuggestionsProps = {
+  /**
+   * Status of the chat
+   */
+  status: ChatStatus;
+  /**
+   * List of prompt suggestions
+   */
+  suggestions?: string[];
+  /**
+   * Callback when a suggestion is clicked
+   */
+  onSuggestionClick?: (suggestion: string) => void;
+  /**
+   * Custom loading component
+   */
+  loadingComponent?: () => JSX.Element;
+  /**
+   * Optional class names
+   */
+  classNames?: PromptSuggestionsClassNames;
+  /**
+   * Optional translations
+   */
+  translations?: PromptSuggestionsTranslations;
+};
+
+export function createPromptSuggestionsComponent({
+  createElement,
+}: Pick<Renderer, 'createElement'>) {
+  const Button = createButtonComponent({ createElement });
+
+  return function PromptSuggestions(userProps: PromptSuggestionsProps) {
+    const {
+      status,
+      suggestions,
+      onSuggestionClick,
+      loadingComponent: LoadingComponent,
+      classNames = {},
+      translations: userTranslations,
+    } = userProps;
+
+    const cssClasses = {
+      root: cx('ais-PromptSuggestions', classNames.root),
+      header: cx('ais-PromptSuggestions-header', classNames.header),
+      suggestionsList: cx(
+        'ais-PromptSuggestions-list',
+        classNames.suggestionsList
+      ),
+      suggestionItem: cx(
+        'ais-PromptSuggestions-item',
+        classNames.suggestionItem
+      ),
+      loading: cx('ais-PromptSuggestions-loading', classNames.loading),
+    };
+
+    const translations: Required<PromptSuggestionsTranslations> = {
+      suggestionsHeaderText: 'Suggestions',
+      ...userTranslations,
+    };
+
+    if (status === 'streaming') {
+      return LoadingComponent ? (
+        <LoadingComponent />
+      ) : (
+        <span className={cssClasses.loading}>Loading suggestions...</span>
+      );
+    }
+
+    if (status === 'ready' && suggestions && suggestions.length > 0) {
+      return (
+        <div className={cssClasses.root}>
+          <h3 className={cssClasses.header}>
+            {translations.suggestionsHeaderText}
+          </h3>
+
+          <ul className={cssClasses.suggestionsList}>
+            {suggestions.map((suggestion, index) => (
+              <li key={index} className={cssClasses.suggestionItem}>
+                <Button
+                  variant="ghost"
+                  onClick={() => onSuggestionClick?.(suggestion)}
+                >
+                  {suggestion}
+                </Button>
+              </li>
+            ))}
+          </ul>
+        </div>
+      );
+    }
+
+    return null;
+  };
+}

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

@@ -9,6 +9,7 @@ export * from './chat/ChatMessageLoader';
 export * from './chat/ChatMessageError';
 export * from './chat/ChatPrompt';
 export * from './chat/ChatToggleButton';
+export * from './chat/PromptSuggestions';
 export * from './chat/icons';
 export * from './chat/types';
 export * from './FrequentlyBoughtTogether';

packages/instantsearch.js/src/connectors/chat/connectChat.ts

@@ -28,6 +28,7 @@ import type {
   InstantSearch,
   IndexUiState,
   IndexWidget,
+  WidgetRenderState,
 } from '../../types';
 import type {
   AddToolResultWithOutput,
@@ -76,6 +77,10 @@ export type ChatRenderState<TUiMessage extends UIMessage = UIMessage> = {
    * Tools configuration with addToolResult bound, ready to be used by the UI.
    */
   tools: ClientSideTools;
+  /**
+   * Suggestions received from the AI model.
+   */
+  suggestions?: string[];
 } & Pick<
   AbstractChat<TUiMessage>,
   | 'addToolResult'
@@ -120,7 +125,12 @@ export type ChatConnectorParams<TUiMessage extends UIMessage = UIMessage> = (
 export type ChatWidgetDescription<TUiMessage extends UIMessage = UIMessage> = {
   $$type: 'ais.chat';
   renderState: ChatRenderState<TUiMessage>;
-  indexRenderState: Record<string, unknown>;
+  indexRenderState: {
+    chat: WidgetRenderState<
+      ChatRenderState<TUiMessage>,
+      ChatConnectorParams<TUiMessage>
+    >;
+  };
 };
 
 export type ChatConnector<TUiMessage extends UIMessage = UIMessage> = Connector<
@@ -149,6 +159,7 @@ export default (function connectChat<TWidgetParams extends UnknownWidgetParams>(
     let setInput: ChatRenderState<TUiMessage>['setInput'];
     let setOpen: ChatRenderState<TUiMessage>['setOpen'];
     let setIsClearing: (value: boolean) => void;
+    let suggestions: string[] | undefined;
 
     const setMessages = (
       messagesParam: TUiMessage[] | ((m: TUiMessage[]) => TUiMessage[])
@@ -210,6 +221,11 @@ export default (function connectChat<TWidgetParams extends UnknownWidgetParams>(
         ...options,
         transport,
         sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls,
+        onData: ({ data }) => {
+          if (data && typeof data === 'object' && 'suggestions' in data) {
+            suggestions = (data as any).suggestions as string[] | undefined;
+          }
+        },
         onToolCall({ toolCall }) {
           const tool = tools[toolCall.toolName];
 
@@ -306,8 +322,11 @@ export default (function connectChat<TWidgetParams extends UnknownWidgetParams>(
         );
       },
 
-      getRenderState(renderState) {
-        return renderState;
+      getRenderState(renderState, renderOptions) {
+        return {
+          ...renderState,
+          chat: this.getWidgetRenderState(renderOptions),
+        };
       },
 
       getWidgetRenderState(renderState) {
@@ -342,6 +361,7 @@ export default (function connectChat<TWidgetParams extends UnknownWidgetParams>(
           setInput,
           setOpen,
           setMessages,
+          suggestions,
           isClearing,
           clearMessages,
           onClearTransitionEnd,

packages/instantsearch.js/src/lib/chat/chat.ts

@@ -76,6 +76,10 @@ export class ChatState<TUiMessage extends UIMessage>
     this._callMessagesCallbacks();
   }
 
+  get data(): unknown {
+    return this.data;
+  }
+
   pushMessage = (message: TUiMessage) => {
     this._messages = this._messages.concat(message);
     this._callMessagesCallbacks();
@@ -150,6 +154,10 @@ export class Chat<
     this._state = state;
   }
 
+  get data() {
+    return this._state.data;
+  }
+
   '~registerMessagesCallback' = (onChange: () => void): (() => void) =>
     this._state['~registerMessagesCallback'](onChange);