@docusaurus/theme-search-algolia 3.8.1 → 3.9.0-canary-6403

package/lib/theme/SearchTranslations/index.js

@@ -5,6 +5,12 @@
  * LICENSE file in the root directory of this source tree.
  */
 import {translate} from '@docusaurus/Translate';
+// TODO Docusaurus v4: require DocSearch v4
+//  This needs to be cleaned after the upgrade
+//  Docusaurus v3 was made compatible with both DocSearch v3 and v4
+//  This implies that labels have been kept retro-compatible with v3
+//  Once we upgrade, we should be able to rely on v4 types only
+//  and remove v3 retro-compatibility labels that do not exist anymore in v4
 const translations = {
   button: {
     buttonText: translate({
@@ -40,6 +46,68 @@ const translations = {
         message: 'Cancel',
         description: 'The label and ARIA label for search box cancel button',
       }),
+      // v4
+      clearButtonTitle: translate({
+        id: 'theme.SearchModal.searchBox.resetButtonTitle',
+        message: 'Clear the query',
+        description: 'The label and ARIA label for search box reset button',
+      }),
+      clearButtonAriaLabel: translate({
+        id: 'theme.SearchModal.searchBox.resetButtonTitle',
+        message: 'Clear the query',
+        description: 'The label and ARIA label for search box reset button',
+      }),
+      closeButtonText: translate({
+        id: 'theme.SearchModal.searchBox.cancelButtonText',
+        message: 'Cancel',
+        description: 'The label and ARIA label for search box cancel button',
+      }),
+      closeButtonAriaLabel: translate({
+        id: 'theme.SearchModal.searchBox.cancelButtonText',
+        message: 'Cancel',
+        description: 'The label and ARIA label for search box cancel button',
+      }),
+      placeholderText: translate({
+        id: 'theme.SearchModal.searchBox.placeholderText',
+        message: 'Search docs',
+        description: 'The placeholder text for the main search input field',
+      }),
+      placeholderTextAskAi: translate({
+        id: 'theme.SearchModal.searchBox.placeholderTextAskAi',
+        message: 'Ask another question...',
+        description: 'The placeholder text when in AI question mode',
+      }),
+      placeholderTextAskAiStreaming: translate({
+        id: 'theme.SearchModal.searchBox.placeholderTextAskAiStreaming',
+        message: 'Answering...',
+        description:
+          'The placeholder text for search box when AI is streaming an answer',
+      }),
+      enterKeyHint: translate({
+        id: 'theme.SearchModal.searchBox.enterKeyHint',
+        message: 'search',
+        description: 'The hint for the search box enter key text',
+      }),
+      enterKeyHintAskAi: translate({
+        id: 'theme.SearchModal.searchBox.enterKeyHintAskAi',
+        message: 'enter',
+        description: 'The hint for the Ask AI search box enter key text',
+      }),
+      searchInputLabel: translate({
+        id: 'theme.SearchModal.searchBox.searchInputLabel',
+        message: 'Search',
+        description: 'The ARIA label for search input',
+      }),
+      backToKeywordSearchButtonText: translate({
+        id: 'theme.SearchModal.searchBox.backToKeywordSearchButtonText',
+        message: 'Back to keyword search',
+        description: 'The text for back to keyword search button',
+      }),
+      backToKeywordSearchButtonAriaLabel: translate({
+        id: 'theme.SearchModal.searchBox.backToKeywordSearchButtonAriaLabel',
+        message: 'Back to keyword search',
+        description: 'The ARIA label for back to keyword search button',
+      }),
     },
     startScreen: {
       recentSearchesTitle: translate({
@@ -50,17 +118,17 @@ const translations = {
       noRecentSearchesText: translate({
         id: 'theme.SearchModal.startScreen.noRecentSearchesText',
         message: 'No recent searches',
-        description: 'The text when no recent searches',
+        description: 'The text when there are no recent searches',
       }),
       saveRecentSearchButtonTitle: translate({
         id: 'theme.SearchModal.startScreen.saveRecentSearchButtonTitle',
         message: 'Save this search',
-        description: 'The label for save recent search button',
+        description: 'The title for save recent search button',
       }),
       removeRecentSearchButtonTitle: translate({
         id: 'theme.SearchModal.startScreen.removeRecentSearchButtonTitle',
         message: 'Remove this search from history',
-        description: 'The label for remove recent search button',
+        description: 'The title for remove recent search button',
       }),
       favoriteSearchesTitle: translate({
         id: 'theme.SearchModal.startScreen.favoriteSearchesTitle',
@@ -70,91 +138,178 @@ const translations = {
       removeFavoriteSearchButtonTitle: translate({
         id: 'theme.SearchModal.startScreen.removeFavoriteSearchButtonTitle',
         message: 'Remove this search from favorites',
-        description: 'The label for remove favorite search button',
+        description: 'The title for remove favorite search button',
+      }),
+      recentConversationsTitle: translate({
+        id: 'theme.SearchModal.startScreen.recentConversationsTitle',
+        message: 'Recent conversations',
+        description: 'The title for recent conversations',
+      }),
+      removeRecentConversationButtonTitle: translate({
+        id: 'theme.SearchModal.startScreen.removeRecentConversationButtonTitle',
+        message: 'Remove this conversation from history',
+        description: 'The title for remove recent conversation button',
       }),
     },
     errorScreen: {
       titleText: translate({
         id: 'theme.SearchModal.errorScreen.titleText',
         message: 'Unable to fetch results',
-        description: 'The title for error screen of search modal',
+        description: 'The title for error screen',
       }),
       helpText: translate({
         id: 'theme.SearchModal.errorScreen.helpText',
         message: 'You might want to check your network connection.',
-        description: 'The help text for error screen of search modal',
+        description: 'The help text for error screen',
+      }),
+    },
+    resultsScreen: {
+      askAiPlaceholder: translate({
+        id: 'theme.SearchModal.resultsScreen.askAiPlaceholder',
+        message: 'Ask AI: ',
+        description: 'The placeholder text for Ask AI input',
+      }),
+    },
+    askAiScreen: {
+      disclaimerText: translate({
+        id: 'theme.SearchModal.askAiScreen.disclaimerText',
+        message:
+          'Answers are generated with AI which can make mistakes. Verify responses.',
+        description: 'The disclaimer text for AI answers',
+      }),
+      relatedSourcesText: translate({
+        id: 'theme.SearchModal.askAiScreen.relatedSourcesText',
+        message: 'Related sources',
+        description: 'The text for related sources',
+      }),
+      thinkingText: translate({
+        id: 'theme.SearchModal.askAiScreen.thinkingText',
+        message: 'Thinking...',
+        description: 'The text when AI is thinking',
+      }),
+      copyButtonText: translate({
+        id: 'theme.SearchModal.askAiScreen.copyButtonText',
+        message: 'Copy',
+        description: 'The text for copy button',
+      }),
+      copyButtonCopiedText: translate({
+        id: 'theme.SearchModal.askAiScreen.copyButtonCopiedText',
+        message: 'Copied!',
+        description: 'The text for copy button when copied',
+      }),
+      copyButtonTitle: translate({
+        id: 'theme.SearchModal.askAiScreen.copyButtonTitle',
+        message: 'Copy',
+        description: 'The title for copy button',
+      }),
+      likeButtonTitle: translate({
+        id: 'theme.SearchModal.askAiScreen.likeButtonTitle',
+        message: 'Like',
+        description: 'The title for like button',
+      }),
+      dislikeButtonTitle: translate({
+        id: 'theme.SearchModal.askAiScreen.dislikeButtonTitle',
+        message: 'Dislike',
+        description: 'The title for dislike button',
+      }),
+      thanksForFeedbackText: translate({
+        id: 'theme.SearchModal.askAiScreen.thanksForFeedbackText',
+        message: 'Thanks for your feedback!',
+        description: 'The text for thanks for feedback',
+      }),
+      preToolCallText: translate({
+        id: 'theme.SearchModal.askAiScreen.preToolCallText',
+        message: 'Searching...',
+        description: 'The text before tool call',
+      }),
+      duringToolCallText: translate({
+        id: 'theme.SearchModal.askAiScreen.duringToolCallText',
+        message: 'Searching for ',
+        description: 'The text during tool call',
+      }),
+      afterToolCallText: translate({
+        id: 'theme.SearchModal.askAiScreen.afterToolCallText',
+        message: 'Searched for',
+        description: 'The text after tool call',
       }),
     },
     footer: {
       selectText: translate({
         id: 'theme.SearchModal.footer.selectText',
-        message: 'to select',
-        description: 'The explanatory text of the action for the enter key',
+        message: 'Select',
+        description: 'The select text for footer',
+      }),
+      submitQuestionText: translate({
+        id: 'theme.SearchModal.footer.submitQuestionText',
+        message: 'Submit question',
+        description: 'The submit question text for footer',
       }),
       selectKeyAriaLabel: translate({
         id: 'theme.SearchModal.footer.selectKeyAriaLabel',
         message: 'Enter key',
-        description:
-          'The ARIA label for the Enter key button that makes the selection',
+        description: 'The ARIA label for select key in footer',
       }),
       navigateText: translate({
         id: 'theme.SearchModal.footer.navigateText',
-        message: 'to navigate',
-        description:
-          'The explanatory text of the action for the Arrow up and Arrow down key',
+        message: 'Navigate',
+        description: 'The navigate text for footer',
       }),
       navigateUpKeyAriaLabel: translate({
         id: 'theme.SearchModal.footer.navigateUpKeyAriaLabel',
         message: 'Arrow up',
-        description:
-          'The ARIA label for the Arrow up key button that makes the navigation',
+        description: 'The ARIA label for navigate up key in footer',
       }),
       navigateDownKeyAriaLabel: translate({
         id: 'theme.SearchModal.footer.navigateDownKeyAriaLabel',
         message: 'Arrow down',
-        description:
-          'The ARIA label for the Arrow down key button that makes the navigation',
+        description: 'The ARIA label for navigate down key in footer',
       }),
       closeText: translate({
         id: 'theme.SearchModal.footer.closeText',
-        message: 'to close',
-        description: 'The explanatory text of the action for Escape key',
+        message: 'Close',
+        description: 'The close text for footer',
       }),
       closeKeyAriaLabel: translate({
         id: 'theme.SearchModal.footer.closeKeyAriaLabel',
         message: 'Escape key',
-        description:
-          'The ARIA label for the Escape key button that close the modal',
+        description: 'The ARIA label for close key in footer',
+      }),
+      poweredByText: translate({
+        id: 'theme.SearchModal.footer.searchByText',
+        message: 'Powered by',
+        description: "The 'Powered by' text for footer",
       }),
       searchByText: translate({
         id: 'theme.SearchModal.footer.searchByText',
-        message: 'Search by',
-        description: 'The text explain that the search is making by Algolia',
+        message: 'Powered by',
+        description: "The 'Powered by' text for footer",
+      }),
+      backToSearchText: translate({
+        id: 'theme.SearchModal.footer.backToSearchText',
+        message: 'Back to search',
+        description: 'The back to search text for footer',
       }),
     },
     noResultsScreen: {
       noResultsText: translate({
         id: 'theme.SearchModal.noResultsScreen.noResultsText',
-        message: 'No results for',
-        description:
-          'The text explains that there are no results for the following search',
+        message: 'No results found for',
+        description: 'The text when there are no results',
       }),
       suggestedQueryText: translate({
         id: 'theme.SearchModal.noResultsScreen.suggestedQueryText',
         message: 'Try searching for',
-        description:
-          'The text for the suggested query when no results are found for the following search',
+        description: 'The text for suggested query',
       }),
       reportMissingResultsText: translate({
         id: 'theme.SearchModal.noResultsScreen.reportMissingResultsText',
         message: 'Believe this query should return results?',
-        description:
-          'The text for the question where the user thinks there are missing results',
+        description: 'The text for reporting missing results',
       }),
       reportMissingResultsLinkText: translate({
         id: 'theme.SearchModal.noResultsScreen.reportMissingResultsLinkText',
         message: 'Let us know.',
-        description: 'The text for the link to report missing results',
+        description: 'The link text for reporting missing results',
       }),
     },
   },

package/lib/validateThemeConfig.d.ts

@@ -5,11 +5,12 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { Joi } from '@docusaurus/utils-validation';
-import type { ThemeConfig, ThemeConfigValidationContext } from '@docusaurus/types';
+import type { ThemeConfigValidationContext } from '@docusaurus/types';
+import type { ThemeConfig } from '@docusaurus/theme-search-algolia';
 export declare const DEFAULT_CONFIG: {
-    contextualSearch: boolean;
+    contextualSearch: true;
     searchParameters: {};
     searchPagePath: string;
 };
 export declare const Schema: Joi.ObjectSchema<ThemeConfig>;
-export declare function validateThemeConfig({ validate, themeConfig, }: ThemeConfigValidationContext<ThemeConfig>): ThemeConfig;
+export declare function validateThemeConfig({ validate, themeConfig: themeConfigInput, }: ThemeConfigValidationContext<ThemeConfig>): ThemeConfig;

package/lib/validateThemeConfig.js

@@ -10,6 +10,7 @@ exports.Schema = exports.DEFAULT_CONFIG = void 0;
 exports.validateThemeConfig = validateThemeConfig;
 const utils_1 = require("@docusaurus/utils");
 const utils_validation_1 = require("@docusaurus/utils-validation");
+const docSearchVersion_1 = require("./docSearchVersion");
 exports.DEFAULT_CONFIG = {
     // Enabled by default, as it makes sense in most cases
     // see also https://github.com/facebook/docusaurus/issues/5880
@@ -17,6 +18,7 @@ exports.DEFAULT_CONFIG = {
     searchParameters: {},
     searchPagePath: 'search',
 };
+const FacetFiltersSchema = utils_validation_1.Joi.array().items(utils_validation_1.Joi.alternatives().try(utils_validation_1.Joi.string(), utils_validation_1.Joi.array().items(utils_validation_1.Joi.string())));
 exports.Schema = utils_validation_1.Joi.object({
     algolia: utils_validation_1.Joi.object({
         // Docusaurus attributes
@@ -28,7 +30,9 @@ exports.Schema = utils_validation_1.Joi.object({
         }),
         apiKey: utils_validation_1.Joi.string().required(),
         indexName: utils_validation_1.Joi.string().required(),
-        searchParameters: utils_validation_1.Joi.object()
+        searchParameters: utils_validation_1.Joi.object({
+            facetFilters: FacetFiltersSchema.optional(),
+        })
             .default(exports.DEFAULT_CONFIG.searchParameters)
             .unknown(),
         searchPagePath: utils_validation_1.Joi.alternatives()
@@ -47,11 +51,69 @@ exports.Schema = utils_validation_1.Joi.object({
             }).required(),
             to: utils_validation_1.Joi.string().required(),
         }).optional(),
+        // Ask AI configuration (DocSearch v4 only)
+        askAi: utils_validation_1.Joi.alternatives()
+            .try(
+        // Simple string format (assistantId only)
+        utils_validation_1.Joi.string(), 
+        // Full configuration object
+        utils_validation_1.Joi.object({
+            indexName: utils_validation_1.Joi.string().required(),
+            apiKey: utils_validation_1.Joi.string().required(),
+            appId: utils_validation_1.Joi.string().required(),
+            assistantId: utils_validation_1.Joi.string().required(),
+            searchParameters: utils_validation_1.Joi.object({
+                facetFilters: FacetFiltersSchema.optional(),
+            }).optional(),
+        }))
+            .custom((askAiInput, helpers) => {
+            if (!askAiInput) {
+                return askAiInput;
+            }
+            const algolia = helpers.state.ancestors[0];
+            const algoliaFacetFilters = algolia.searchParameters?.facetFilters;
+            if (typeof askAiInput === 'string') {
+                return {
+                    assistantId: askAiInput,
+                    indexName: algolia.indexName,
+                    apiKey: algolia.apiKey,
+                    appId: algolia.appId,
+                    ...(algoliaFacetFilters
+                        ? {
+                            searchParameters: {
+                                facetFilters: algoliaFacetFilters,
+                            },
+                        }
+                        : {}),
+                };
+            }
+            if (askAiInput.searchParameters?.facetFilters === undefined &&
+                algoliaFacetFilters) {
+                askAiInput.searchParameters = askAiInput.searchParameters ?? {};
+                askAiInput.searchParameters.facetFilters = algoliaFacetFilters;
+            }
+            return askAiInput;
+        })
+            .optional()
+            .messages({
+            'alternatives.types': 'askAi must be either a string (assistantId) or an object with indexName, apiKey, appId, and assistantId',
+        }),
     })
         .label('themeConfig.algolia')
         .required()
-        .unknown(), // DocSearch 3 is still alpha: don't validate the rest for now
+        .unknown(),
 });
-function validateThemeConfig({ validate, themeConfig, }) {
-    return validate(exports.Schema, themeConfig);
+// TODO Docusaurus v4: remove this check when we drop DocSearch v3
+function ensureAskAISupported(themeConfig) {
+    // enforce DocsSearch v4 requirement when AskAI is configured
+    if (themeConfig.algolia.askAi && docSearchVersion_1.docSearchV3) {
+        throw new Error('The askAi feature is only supported in DocSearch v4. ' +
+            'Please upgrade to DocSearch v4 by installing "@docsearch/react": "^4.0.0" ' +
+            'or remove the askAi configuration from your theme config.');
+    }
+}
+function validateThemeConfig({ validate, themeConfig: themeConfigInput, }) {
+    const themeConfig = validate(exports.Schema, themeConfigInput);
+    ensureAskAISupported(themeConfig);
+    return themeConfig;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/theme-search-algolia",
-  "version": "3.8.1",
+  "version": "3.9.0-canary-6403",
   "description": "Algolia search component for Docusaurus.",
   "main": "lib/index.js",
   "sideEffects": [
@@ -33,16 +33,16 @@
     "copy:watch": "node ../../admin/scripts/copyUntypedFiles.js --watch"
   },
   "dependencies": {
-    "@docsearch/react": "^3.9.0",
-    "@docusaurus/core": "3.8.1",
-    "@docusaurus/logger": "3.8.1",
-    "@docusaurus/plugin-content-docs": "3.8.1",
-    "@docusaurus/theme-common": "3.8.1",
-    "@docusaurus/theme-translations": "3.8.1",
-    "@docusaurus/utils": "3.8.1",
-    "@docusaurus/utils-validation": "3.8.1",
-    "algoliasearch": "^5.17.1",
-    "algoliasearch-helper": "^3.22.6",
+    "@docsearch/react": "^3.9.0 || ^4.1.0",
+    "@docusaurus/core": "3.9.0-canary-6403",
+    "@docusaurus/logger": "3.9.0-canary-6403",
+    "@docusaurus/plugin-content-docs": "3.9.0-canary-6403",
+    "@docusaurus/theme-common": "3.9.0-canary-6403",
+    "@docusaurus/theme-translations": "3.9.0-canary-6403",
+    "@docusaurus/utils": "3.9.0-canary-6403",
+    "@docusaurus/utils-validation": "3.9.0-canary-6403",
+    "algoliasearch": "^5.37.0",
+    "algoliasearch-helper": "^3.26.0",
     "clsx": "^2.0.0",
     "eta": "^2.2.0",
     "fs-extra": "^11.1.1",
@@ -51,14 +51,14 @@
     "utility-types": "^3.10.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "3.8.1"
+    "@docusaurus/module-type-aliases": "3.9.0-canary-6403"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "engines": {
-    "node": ">=18.0"
+    "node": ">=20.0"
   },
-  "gitHead": "fa8ae13e668fcbc0481ce10c0a734e2a5b397293"
+  "gitHead": "22c95f8cb5c070ce47e115be376fa9b828dd54df"
 }

package/src/client/index.ts

@@ -6,5 +6,10 @@
  */
 
 export {useAlgoliaThemeConfig} from './useAlgoliaThemeConfig';
-export {useAlgoliaContextualFacetFilters} from './useAlgoliaContextualFacetFilters';
+export {
+  useAlgoliaContextualFacetFilters,
+  useAlgoliaContextualFacetFiltersIfEnabled,
+} from './useAlgoliaContextualFacetFilters';
 export {useSearchResultUrlProcessor} from './useSearchResultUrlProcessor';
+export {useAlgoliaAskAi} from './useAlgoliaAskAi';
+export {mergeFacetFilters} from './utils';

package/src/client/useAlgoliaAskAi.ts

@@ -0,0 +1,108 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {useCallback, useMemo, useState} from 'react';
+import {version as docsearchVersion} from '@docsearch/react/version';
+import translations from '@theme/SearchTranslations';
+import {useAlgoliaContextualFacetFiltersIfEnabled} from './useAlgoliaContextualFacetFilters';
+import {mergeFacetFilters} from './utils';
+import type {AskAiConfig} from '@docusaurus/theme-search-algolia';
+import type {
+  DocSearchModalProps,
+  DocSearchTranslations,
+} from '@docsearch/react';
+import type {FacetFilters} from 'algoliasearch/lite';
+
+// The minimal props the hook needs from DocSearch v4 props
+// TODO Docusaurus v4: cleanup after we drop support for DocSearch v3
+interface DocSearchV4PropsLite {
+  indexName: string;
+  apiKey: string;
+  appId: string;
+  placeholder?: string;
+  translations?: DocSearchTranslations;
+  searchParameters?: DocSearchModalProps['searchParameters'];
+  askAi?: AskAiConfig;
+}
+
+const isV4 = docsearchVersion.startsWith('4.');
+
+type UseAskAiResult = {
+  canHandleAskAi: boolean;
+  isAskAiActive: boolean;
+  currentPlaceholder: string | undefined;
+  onAskAiToggle: (active: boolean) => void;
+  askAi?: AskAiConfig;
+  extraAskAiProps: Partial<DocSearchModalProps> & {
+    askAi?: AskAiConfig;
+    canHandleAskAi?: boolean;
+    isAskAiActive?: boolean;
+    onAskAiToggle?: (active: boolean) => void;
+  };
+};
+
+// We need to apply contextualSearch facetFilters to AskAI filters
+// This can't be done at config normalization time because contextual filters
+// can only be determined at runtime
+function applyAskAiContextualSearch(
+  askAi: AskAiConfig | undefined,
+  contextualSearchFilters: FacetFilters | undefined,
+): AskAiConfig | undefined {
+  if (!askAi) {
+    return undefined;
+  }
+  if (!contextualSearchFilters) {
+    return askAi;
+  }
+  const askAiFacetFilters = askAi.searchParameters?.facetFilters;
+  return {
+    ...askAi,
+    searchParameters: {
+      ...askAi.searchParameters,
+      facetFilters: mergeFacetFilters(
+        askAiFacetFilters,
+        contextualSearchFilters,
+      ),
+    },
+  };
+}
+
+export function useAlgoliaAskAi(props: DocSearchV4PropsLite): UseAskAiResult {
+  const [isAskAiActive, setIsAskAiActive] = useState(false);
+  const contextualSearchFilters = useAlgoliaContextualFacetFiltersIfEnabled();
+
+  const askAi = useMemo(() => {
+    return applyAskAiContextualSearch(props.askAi, contextualSearchFilters);
+  }, [props.askAi, contextualSearchFilters]);
+
+  const canHandleAskAi = Boolean(askAi);
+
+  const currentPlaceholder =
+    isAskAiActive && isV4
+      ? translations.modal?.searchBox?.placeholderTextAskAi
+      : translations.modal?.searchBox?.placeholderText || props?.placeholder;
+
+  const onAskAiToggle = useCallback((askAiToggle: boolean) => {
+    setIsAskAiActive(askAiToggle);
+  }, []);
+
+  const extraAskAiProps: UseAskAiResult['extraAskAiProps'] = {
+    askAi,
+    canHandleAskAi,
+    isAskAiActive,
+    onAskAiToggle,
+  };
+
+  return {
+    canHandleAskAi,
+    isAskAiActive,
+    currentPlaceholder,
+    onAskAiToggle,
+    askAi,
+    extraAskAiProps,
+  };
+}

package/src/client/useAlgoliaContextualFacetFilters.ts

@@ -8,6 +8,8 @@
 import {DEFAULT_SEARCH_TAG} from '@docusaurus/theme-common/internal';
 import {useDocsContextualSearchTags} from '@docusaurus/plugin-content-docs/client';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import {useAlgoliaThemeConfig} from './useAlgoliaThemeConfig';
+import type {FacetFilters} from 'algoliasearch/lite';
 
 function useSearchTags() {
   // only docs have custom search tags per version
@@ -16,7 +18,7 @@ function useSearchTags() {
 }
 
 // Translate search-engine agnostic search tags to Algolia search filters
-export function useAlgoliaContextualFacetFilters(): [string, string[]] {
+export function useAlgoliaContextualFacetFilters(): FacetFilters {
   const locale = useDocusaurusContext().i18n.currentLocale;
   const tags = useSearchTags();
 
@@ -27,3 +29,17 @@ export function useAlgoliaContextualFacetFilters(): [string, string[]] {
 
   return [languageFilter, tagsFilter];
 }
+
+export function useAlgoliaContextualFacetFiltersIfEnabled():
+  | FacetFilters
+  | undefined {
+  const {
+    algolia: {contextualSearch},
+  } = useAlgoliaThemeConfig();
+  const facetFilters = useAlgoliaContextualFacetFilters();
+  if (contextualSearch) {
+    return facetFilters;
+  } else {
+    return undefined;
+  }
+}

package/src/client/utils.ts

@@ -0,0 +1,40 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import type {FacetFilters} from 'algoliasearch/lite';
+
+export function mergeFacetFilters(
+  f1: FacetFilters,
+  f2: FacetFilters,
+): FacetFilters;
+
+export function mergeFacetFilters(
+  f1: FacetFilters | undefined,
+  f2: FacetFilters | undefined,
+): FacetFilters | undefined;
+
+export function mergeFacetFilters(
+  f1: FacetFilters | undefined,
+  f2: FacetFilters | undefined,
+): FacetFilters | undefined {
+  if (f1 === undefined) {
+    return f2;
+  }
+  if (f2 === undefined) {
+    return f1;
+  }
+
+  const normalize = (f: FacetFilters): FacetFilters =>
+    typeof f === 'string' ? [f] : f;
+
+  // Historical behavior: we flatten everything
+  // TODO I'm pretty sure this is incorrect
+  //  see https://www.algolia.com/doc/api-reference/api-parameters/facetFilters/?client=javascript
+  //  Note: Algolia is working to provide a reliable facet merging strategy
+  //  see https://github.com/facebook/docusaurus/pull/11327#issuecomment-3284742923
+  return [...normalize(f1), ...normalize(f2)];
+}