feat(chat): handle setting refinements from the search index tool 'view all' button

bundlesize.config.json

@@ -10,19 +10,19 @@
     },
     {
       "path": "./packages/instantsearch.js/dist/instantsearch.production.min.js",
-      "maxSize": "117 kB"
+      "maxSize": "117.25 kB"
     },
     {
       "path": "./packages/instantsearch.js/dist/instantsearch.development.js",
-      "maxSize": "237.5 kB"
+      "maxSize": "238 kB"
     },
     {
       "path": "packages/react-instantsearch-core/dist/umd/ReactInstantSearchCore.min.js",
-      "maxSize": "61.25 kB"
+      "maxSize": "61.50 kB"
     },
     {
       "path": "packages/react-instantsearch/dist/umd/ReactInstantSearch.min.js",
-      "maxSize": "96.5 kB"
+      "maxSize": "96.75 kB"
     },
     {
       "path": "packages/vue-instantsearch/vue2/umd/index.js",

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

@@ -235,6 +235,7 @@ export function createChatMessageComponent({ createElement }: Renderer) {
                 indexUiState={indexUiState}
                 setIndexUiState={setIndexUiState}
                 addToolResult={boundAddToolResult}
+                applyFilters={tool.applyFilters}
                 onClose={onClose}
               />
             </div>

packages/instantsearch-ui-components/src/components/chat/__tests__/ChatMessage.test.tsx

@@ -226,6 +226,7 @@ describe('ChatMessage', () => {
             ),
             addToolResult: jest.fn(),
             onToolCall: jest.fn(),
+            applyFilters: jest.fn(),
           },
         }}
         onClose={jest.fn()}

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

@@ -1,3 +1,5 @@
+import type { SearchParameters } from 'algoliasearch-helper';
+
 export type ChatStatus = 'ready' | 'submitted' | 'streaming' | 'error';
 export type ChatRole = 'data' | 'user' | 'assistant' | 'system';
 
@@ -444,12 +446,24 @@ export type AddToolResultWithOutput = (
   params: Pick<Parameters<AddToolResult>[0], 'output'>
 ) => ReturnType<AddToolResult>;
 
+export type SearchToolInput = {
+  query: string;
+  number_of_results?: number;
+  facet_filters?: string[][];
+};
+
+export type ApplyFiltersParams = {
+  query?: string;
+  facetFilters?: string[][];
+};
+
 export type ClientSideToolComponentProps = {
   message: ChatToolMessage;
   indexUiState: object;
   setIndexUiState: (state: object) => void;
   onClose: () => void;
   addToolResult: AddToolResultWithOutput;
+  applyFilters: (params: ApplyFiltersParams) => SearchParameters;
 };
 
 export type ClientSideToolComponent = (
@@ -466,8 +480,12 @@ export type ClientSideTool = {
       addToolResult: AddToolResultWithOutput;
     }
   ) => void;
+  applyFilters: (params: ApplyFiltersParams) => SearchParameters;
 };
 export type ClientSideTools = Record<string, ClientSideTool>;
 
-export type UserClientSideTool = Omit<ClientSideTool, 'addToolResult'>;
+export type UserClientSideTool = Omit<
+  ClientSideTool,
+  'addToolResult' | 'applyFilters'
+>;
 export type UserClientSideTools = Record<string, UserClientSideTool>;

packages/instantsearch.js/src/__tests__/common-widgets.test.tsx

@@ -621,11 +621,40 @@ const testSetups: TestSetupsMap<TestSuites, 'javascript'> = {
       .start();
   },
   createChatWidgetTests({ instantSearchOptions, widgetParams }) {
+    const { renderRefinements, ...chatWidgetParams } = widgetParams;
+
+    const refinementsWidgets = [];
+    if (renderRefinements) {
+      refinementsWidgets.push(
+        ...[
+          searchBox({
+            container: document.body.appendChild(document.createElement('div')),
+          }),
+          refinementList({
+            container: document.body.appendChild(document.createElement('div')),
+            attribute: 'brand',
+          }),
+          refinementList({
+            container: document.body.appendChild(document.createElement('div')),
+            attribute: 'category',
+          }),
+          hierarchicalMenu({
+            container: document.body.appendChild(document.createElement('div')),
+            attributes: [
+              'hierarchicalCategories.lvl0',
+              'hierarchicalCategories.lvl1',
+            ],
+          }),
+        ]
+      );
+    }
+
     instantsearch(instantSearchOptions)
       .addWidgets([
+        ...refinementsWidgets,
         chat({
           container: document.body.appendChild(document.createElement('div')),
-          ...widgetParams,
+          ...chatWidgetParams,
         }),
       ])
       .on('error', () => {

packages/instantsearch.js/src/connectors/chat/__tests__/connectChat-test.ts

@@ -386,6 +386,7 @@ describe('connectChat', () => {
         testTool: {
           ...mockTool,
           addToolResult: expect.any(Function),
+          applyFilters: expect.any(Function),
         },
       });
     });

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

@@ -5,13 +5,17 @@ import {
 import { Chat } from '../../lib/chat';
 import {
   checkRendering,
+  clearRefinements,
   createDocumentationMessageGenerator,
   createSendEventForHits,
   getAlgoliaAgent,
   getAppIdAndApiKey,
+  getRefinements,
   noop,
+  uniq,
   warning,
 } from '../../lib/utils';
+import { flat } from '../../lib/utils/flat';
 
 import type {
   AbstractChat,
@@ -30,6 +34,7 @@ import type {
   WidgetRenderState,
   IndexRenderState,
 } from '../../types';
+import type { AlgoliaSearchHelper, SearchResults } from 'algoliasearch-helper';
 import type {
   AddToolResultWithOutput,
   UserClientSideTool,
@@ -105,6 +110,11 @@ export type ChatTransport = {
   transport?: ConstructorParameters<typeof DefaultChatTransport>[0];
 };
 
+export type ApplyFiltersParams = {
+  query?: string;
+  facetFilters?: string[][];
+};
+
 export type ChatInit<TUiMessage extends UIMessage> =
   ChatInitWithoutTransport<TUiMessage> & ChatTransport;
 
@@ -144,6 +154,73 @@ export type ChatConnector<TUiMessage extends UIMessage = UIMessage> = Connector<
   ChatConnectorParams<TUiMessage>
 >;
 
+function getAttributesToClear({
+  results,
+  helper,
+}: {
+  results: SearchResults;
+  helper: AlgoliaSearchHelper;
+}) {
+  return uniq(
+    getRefinements(results, helper.state, true).map(
+      (refinement) => refinement.attribute
+    )
+  );
+}
+
+function updateStateFromSearchToolInput(
+  params: ApplyFiltersParams,
+  helper: AlgoliaSearchHelper
+) {
+  // clear all filters first
+  const attributesToClear = getAttributesToClear({
+    results: helper.lastResults!,
+    helper,
+  });
+
+  helper.setState(
+    clearRefinements({
+      helper,
+      attributesToClear,
+    })
+  );
+
+  if (params.facetFilters) {
+    const attributes = flat(params.facetFilters).map((filter) => {
+      const [attribute, value] = filter.split(':');
+
+      return { attribute, value };
+    });
+
+    attributes.forEach(({ attribute, value }) => {
+      if (
+        !helper.state.isConjunctiveFacet(attribute) &&
+        !helper.state.isHierarchicalFacet(attribute) &&
+        !helper.state.isDisjunctiveFacet(attribute)
+      ) {
+        const s = helper.state.addDisjunctiveFacet(attribute);
+        helper.setState(s);
+        helper.toggleFacetRefinement(attribute, value);
+      } else {
+        const attr =
+          helper.state.hierarchicalFacets.find(
+            (facet) => facet.name === attribute
+          )?.name || attribute;
+
+        helper.toggleFacetRefinement(attr, value);
+      }
+    });
+  }
+
+  if (params.query) {
+    helper.setQuery(params.query);
+  }
+
+  helper.search();
+
+  return helper.state;
+}
+
 export default (function connectChat<TWidgetParams extends UnknownWidgetParams>(
   renderFn: Renderer<ChatRenderState, TWidgetParams & ChatConnectorParams>,
   unmountFn: Unmounter = noop
@@ -421,7 +498,7 @@ export default (function connectChat<TWidgetParams extends UnknownWidgetParams>(
       },
 
       getWidgetRenderState(renderOptions) {
-        const { instantSearchInstance, parent } = renderOptions;
+        const { instantSearchInstance, parent, helper } = renderOptions;
         if (!_chatInstance) {
           this.init!({ ...renderOptions, uiState: {}, results: undefined });
         }
@@ -434,11 +511,16 @@ export default (function connectChat<TWidgetParams extends UnknownWidgetParams>(
           });
         }
 
+        function applyFilters(params: ApplyFiltersParams) {
+          return updateStateFromSearchToolInput(params, helper);
+        }
+
         const toolsWithAddToolResult: ClientSideTools = {};
         Object.entries(tools).forEach(([key, tool]) => {
           const toolWithAddToolResult: ClientSideTool = {
             ...tool,
             addToolResult: _chatInstance.addToolResult,
+            applyFilters,
           };
           toolsWithAddToolResult[key] = toolWithAddToolResult;
         });

packages/instantsearch.js/src/lib/utils/__tests__/flat-test.ts

@@ -0,0 +1,34 @@
+import { flat } from '../flat';
+
+describe('flat', () => {
+  test('flattens a 2D array into a 1D array', () => {
+    const input = [
+      ['a', 'b'],
+      ['c', 'd'],
+      ['e', 'f'],
+    ];
+    const expectedOutput = ['a', 'b', 'c', 'd', 'e', 'f'];
+
+    const actualOutput = flat(input);
+
+    expect(actualOutput).toEqual(expectedOutput);
+  });
+
+  test('returns an empty array when given an empty array', () => {
+    const input: never[][] = [];
+    const expectedOutput: never[] = [];
+
+    const actualOutput = flat(input);
+
+    expect(actualOutput).toEqual(expectedOutput);
+  });
+
+  test('handles arrays with empty sub-arrays', () => {
+    const input = [['a', 'b'], [], ['c'], [], ['d', 'e']];
+    const expectedOutput = ['a', 'b', 'c', 'd', 'e'];
+
+    const actualOutput = flat(input);
+
+    expect(actualOutput).toEqual(expectedOutput);
+  });
+});

packages/instantsearch.js/src/lib/utils/flat.ts

@@ -0,0 +1,3 @@
+export function flat<T>(arr: T[][]): T[] {
+  return arr.reduce((acc, array) => acc.concat(array), []);
+}