fix: preserve Agent Studio DocSearch options (#5254)

Co-authored-by: Divyansh Singh <40380293+brc-dd@users.noreply.github.com>

__tests__/unit/client/theme-default/support/docsearch.test.ts

@@ -1,5 +1,6 @@
 import {
   buildAskAiConfig,
+  buildSidePanelProps,
   hasAskAi,
   hasKeywordSearch,
   mergeLangFacetFilters,
@@ -192,5 +193,110 @@ describe('client/theme-default/support/docsearch', () => {
       )
       expect(result.searchParameters?.facetFilters).toEqual(['lang:en'])
     })
+
+    test('preserves Agent Studio search parameters by index', () => {
+      const result = buildAskAiConfig(
+        {
+          assistantId: 'assistant123',
+          agentStudio: true,
+          searchParameters: {
+            index: {
+              distinct: false
+            }
+          }
+        } as any,
+        {
+          appId: 'app',
+          apiKey: 'key',
+          indexName: 'index',
+          searchParameters: {
+            facetFilters: ['tag:docs']
+          }
+        } as any,
+        'en'
+      )
+
+      expect(result.searchParameters).toEqual({
+        index: {
+          distinct: false
+        }
+      })
+      expect(result.searchParameters).not.toHaveProperty('facetFilters')
+    })
+
+    test('does not add legacy facet filters to Agent Studio config', () => {
+      const result = buildAskAiConfig(
+        {
+          assistantId: 'assistant123',
+          agentStudio: true
+        } as any,
+        {
+          appId: 'app',
+          apiKey: 'key',
+          indexName: 'index',
+          searchParameters: {
+            facetFilters: ['tag:docs']
+          }
+        } as any,
+        'en'
+      )
+
+      expect(result.searchParameters).toBeUndefined()
+    })
+  })
+
+  describe('buildSidePanelProps', () => {
+    test('passes resolved Ask AI options to the side panel', () => {
+      const result = buildSidePanelProps(
+        {
+          assistantId: 'assistant123',
+          agentStudio: true,
+          searchParameters: {
+            index: {
+              facetFilters: ['lang:en']
+            }
+          },
+          suggestedQuestions: true,
+          useStagingEnv: true,
+          sidePanel: {
+            button: {
+              variant: 'inline'
+            },
+            panel: {
+              width: 420,
+              suggestedQuestions: true
+            }
+          }
+        } as any,
+        {
+          appId: 'app',
+          apiKey: 'key',
+          indexName: 'index'
+        } as any
+      )
+
+      expect(result).toEqual({
+        container: '#vp-docsearch-sidepanel',
+        appId: 'app',
+        apiKey: 'key',
+        indexName: 'index',
+        assistantId: 'assistant123',
+        agentStudio: true,
+        searchParameters: {
+          index: {
+            facetFilters: ['lang:en']
+          }
+        },
+        suggestedQuestions: true,
+        useStagingEnv: true,
+        button: {
+          variant: 'inline'
+        },
+        panel: {
+          width: 420,
+          suggestedQuestions: true
+        }
+      })
+    })
   })
 })

src/client/theme-default/components/VPAlgoliaSearchBox.vue

@@ -1,12 +1,16 @@
 <script setup lang="ts">
 import type { DocSearchInstance, DocSearchProps } from '@docsearch/js'
-import type { SidepanelInstance, SidepanelProps } from '@docsearch/sidepanel-js'
+import type { SidepanelInstance } from '@docsearch/sidepanel-js'
 import { inBrowser, useRouter } from 'vitepress'
 import type { DefaultTheme } from 'vitepress/theme'
 import { nextTick, onUnmounted, watch } from 'vue'
 import type { DocSearchAskAi } from '../../../../types/docsearch'
 import { useData } from '../composables/data'
-import { resolveMode, validateCredentials } from '../support/docsearch'
+import {
+  buildSidePanelProps,
+  resolveMode,
+  validateCredentials
+} from '../support/docsearch'
 
 import '../styles/docsearch.css'
 
@@ -105,12 +109,7 @@ async function initialize(userOptions: DefaultTheme.AlgoliaSearchOptions) {
     if (currentInitialize !== initializeCount) return
 
     sidepanelInstance = sidepanel({
-      ...(askAi.sidePanel === true ? {} : askAi.sidePanel),
-      container: '#vp-docsearch-sidepanel',
-      indexName: askAi.indexName ?? userOptions.indexName,
-      appId: askAi.appId ?? userOptions.appId,
-      apiKey: askAi.apiKey ?? userOptions.apiKey,
-      assistantId: askAi.assistantId,
+      ...buildSidePanelProps(askAi, userOptions),
       onOpen: focusInput,
       onClose: onClose.bind(null, 'sidepanel'),
       onReady: () => {
@@ -122,7 +121,7 @@ async function initialize(userOptions: DefaultTheme.AlgoliaSearchOptions) {
       keyboardShortcuts: {
         'Ctrl/Cmd+I': false
       }
-    } as SidepanelProps)
+    })
   }
 
   const options = {

src/client/theme-default/support/docsearch.ts

@@ -1,3 +1,4 @@
+import type { SidepanelProps } from '@docsearch/sidepanel-js'
 import type { DefaultTheme } from 'vitepress/theme'
 import type { DocSearchAskAi } from '../../../../types/docsearch'
 import { isObject } from '../../shared'
@@ -19,6 +20,14 @@ export interface ResolvedMode {
   useSidePanel: boolean
 }
 
+// FIXME: remove when https://github.com/algolia/docsearch/pull/2906 is released
+export type ResolvedSidePanelProps = SidepanelProps & {
+  agentStudio?: boolean
+  searchParameters?: DocSearchAskAi['searchParameters']
+  suggestedQuestions?: boolean
+  useStagingEnv?: boolean
+}
+
 /**
  * Resolves the effective mode based on config and available features.
  *
@@ -168,10 +177,8 @@ export function buildAskAiConfig(
     !isAskAiString && askAiProp.searchParameters
       ? { ...askAiProp.searchParameters }
       : undefined
+  const isAgentStudio = !isAskAiString && askAiProp.agentStudio === true
 
-  // If Ask AI defines its own facetFilters, merge lang filtering into those.
-  // Otherwise, reuse the keyword search facetFilters so Ask AI follows the
-  // same language filtering behavior by default.
   const askAiFacetFiltersSource =
     askAiSearchParameters?.facetFilters ??
     options.searchParameters?.facetFilters
@@ -180,10 +187,12 @@ export function buildAskAiConfig(
     lang
   )
 
-  const mergedAskAiSearchParameters = {
-    ...askAiSearchParameters,
-    facetFilters: askAiFacetFilters.length ? askAiFacetFilters : undefined
-  }
+  const mergedAskAiSearchParameters = isAgentStudio
+    ? askAiSearchParameters
+    : {
+        ...askAiSearchParameters,
+        facetFilters: askAiFacetFilters.length ? askAiFacetFilters : undefined
+      }
 
   const result: Record<string, any> = {
     ...(isAskAiString ? {} : askAiProp),
@@ -194,13 +203,35 @@ export function buildAskAiConfig(
   }
 
   // Keep `searchParameters` undefined unless it has at least one key.
-  if (Object.values(mergedAskAiSearchParameters).some((v) => v != null)) {
+  if (
+    mergedAskAiSearchParameters &&
+    Object.values(mergedAskAiSearchParameters).some((v) => v != null)
+  ) {
     result.searchParameters = mergedAskAiSearchParameters
   }
 
   return result
 }
 
+/**
+ * Builds the DocSearch side panel config from the resolved Ask AI options.
+ */
+export function buildSidePanelProps(
+  askAi: DocSearchAskAi,
+  options: DefaultTheme.AlgoliaSearchOptions
+): ResolvedSidePanelProps {
+  const { sidePanel, ...askAiRest } = askAi
+
+  return {
+    container: '#vp-docsearch-sidepanel',
+    indexName: options.indexName,
+    appId: options.appId,
+    apiKey: options.apiKey,
+    ...askAiRest,
+    ...(sidePanel && sidePanel !== true ? sidePanel : {})
+  } as ResolvedSidePanelProps
+}
+
 /**
  * Resolves Algolia search options for the given language,
  * merging in locale-specific overrides and language facet filters.