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

package/src/theme/SearchTranslations/index.ts

@@ -9,7 +9,62 @@ import {translate} from '@docusaurus/Translate';
 
 import type {DocSearchTranslations} from '@docsearch/react';
 
-const translations: DocSearchTranslations & {placeholder: string} = {
+// 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: DocSearchTranslations & {
+  placeholder: string;
+  modal: {
+    searchBox: {
+      placeholderText: string;
+      placeholderTextAskAi: string;
+      placeholderTextAskAiStreaming: string;
+      enterKeyHintAskAi: string;
+      searchInputLabel: string;
+      backToKeywordSearchButtonText: string;
+      backToKeywordSearchButtonAriaLabel: string;
+      enterKeyHint: string;
+      clearButtonTitle: string;
+      clearButtonAriaLabel: string;
+      closeButtonText: string;
+      resetButtonTitle: string;
+      resetButtonAriaLabel: string;
+      cancelButtonText: string;
+      cancelButtonAriaLabel: string;
+      closeButtonAriaLabel: string;
+    };
+    startScreen: {
+      recentConversationsTitle: string;
+      removeRecentConversationButtonTitle: string;
+    };
+    resultsScreen: {
+      askAiPlaceholder: string;
+    };
+    askAiScreen: {
+      disclaimerText: string;
+      relatedSourcesText: string;
+      thinkingText: string;
+      copyButtonText: string;
+      copyButtonCopiedText: string;
+      copyButtonTitle: string;
+      likeButtonTitle: string;
+      dislikeButtonTitle: string;
+      thanksForFeedbackText: string;
+      preToolCallText: string;
+      duringToolCallText: string;
+      afterToolCallText: string;
+    };
+    footer: {
+      submitQuestionText: string;
+      poweredByText: string;
+      backToSearchText: string;
+      searchByText: string;
+    };
+  };
+} = {
   button: {
     buttonText: translate({
       id: 'theme.SearchBar.label',
@@ -44,6 +99,69 @@ const translations: DocSearchTranslations & {placeholder: string} = {
         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({
@@ -54,17 +172,17 @@ const translations: DocSearchTranslations & {placeholder: string} = {
       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',
@@ -74,91 +192,178 @@ const translations: DocSearchTranslations & {placeholder: string} = {
       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/src/theme-search-algolia.d.ts

@@ -5,9 +5,27 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+// TODO Docusaurus v4: remove after we drop support for DocSearch v3
+declare module '@docsearch/react/button';
+declare module '@docsearch/react/useDocSearchKeyboardEvents';
+declare module '@docsearch/react/version';
+
 declare module '@docusaurus/theme-search-algolia' {
-  import type {DeepPartial} from 'utility-types';
+  import type {DeepPartial, Overwrite} from 'utility-types';
+
   import type {DocSearchProps} from '@docsearch/react';
+  import type {FacetFilters} from 'algoliasearch/lite';
+
+  // The config after normalization (e.g. AskAI string -> object)
+  export type AskAiConfig = {
+    indexName: string;
+    apiKey: string;
+    appId: string;
+    assistantId: string;
+    searchParameters?: {
+      facetFilters?: FacetFilters;
+    };
+  };
 
   // DocSearch props that Docusaurus exposes directly through props forwarding
   type DocusaurusDocSearchProps = Pick<
@@ -20,9 +38,15 @@ declare module '@docusaurus/theme-search-algolia' {
     | 'searchParameters'
     | 'insights'
     | 'initialQuery'
-  >;
+  > & {
+    // Docusaurus normalizes the AskAI config to an object
+    askAi?: AskAiConfig;
+  };
+
+  export type ThemeConfigAlgolia = DocusaurusDocSearchProps & {
+    // TODO Docusaurus v4: upgrade to DocSearch v4, migrate indexName to indices
+    indexName: string;
 
-  type ThemeConfigAlgolia = DocusaurusDocSearchProps & {
     // Docusaurus custom options, not coming from DocSearch
     contextualSearch: boolean;
     externalUrlRegex?: string;
@@ -33,21 +57,23 @@ declare module '@docusaurus/theme-search-algolia' {
     };
   };
 
-  export type ThemeConfig = DocusaurusDocSearchProps & {
+  export type ThemeConfig = {
     algolia: ThemeConfigAlgolia;
   };
 
-  export type UserThemeConfig = DeepPartial<ThemeConfig>;
-}
-
-declare module '@docusaurus/theme-search-algolia/client' {
-  import type {ThemeConfig} from '@docusaurus/theme-search-algolia';
-
-  export function useAlgoliaThemeConfig(): ThemeConfig;
-
-  export function useAlgoliaContextualFacetFilters(): [string, string[]];
-
-  export function useSearchResultUrlProcessor(): (url: string) => string;
+  export type UserThemeConfig = {
+    algolia?: Overwrite<
+      DeepPartial<ThemeConfigAlgolia>,
+      {
+        // Required fields:
+        appId: ThemeConfigAlgolia['appId'];
+        apiKey: ThemeConfigAlgolia['apiKey'];
+        indexName: ThemeConfigAlgolia['indexName'];
+        // askAi also accepts a shorter string form
+        askAi?: string | AskAiConfig;
+      }
+    >;
+  };
 }
 
 declare module '@theme/SearchPage' {
@@ -65,6 +91,15 @@ declare module '@theme/SearchBar' {
 declare module '@theme/SearchTranslations' {
   import type {DocSearchTranslations} from '@docsearch/react';
 
-  const translations: DocSearchTranslations & {placeholder: string};
+  const translations: DocSearchTranslations & {
+    placeholder: string;
+    // TODO Docusaurus v4: cleanup after we drop support for DocSearch v3
+    modal?: {
+      searchBox?: {
+        placeholderText?: string;
+        placeholderTextAskAi?: string;
+      };
+    };
+  };
   export default translations;
 }

package/src/validateThemeConfig.ts

@@ -7,22 +7,27 @@
 
 import {escapeRegexp} from '@docusaurus/utils';
 import {Joi} from '@docusaurus/utils-validation';
+import {docSearchV3} from './docSearchVersion';
+import type {ThemeConfigValidationContext} from '@docusaurus/types';
 import type {
   ThemeConfig,
-  ThemeConfigValidationContext,
-} from '@docusaurus/types';
+  ThemeConfigAlgolia,
+} from '@docusaurus/theme-search-algolia';
 
 export const DEFAULT_CONFIG = {
   // Enabled by default, as it makes sense in most cases
   // see also https://github.com/facebook/docusaurus/issues/5880
   contextualSearch: true,
-
   searchParameters: {},
   searchPagePath: 'search',
-};
+} satisfies Partial<ThemeConfigAlgolia>;
+
+const FacetFiltersSchema = Joi.array().items(
+  Joi.alternatives().try(Joi.string(), Joi.array().items(Joi.string())),
+);
 
 export const Schema = Joi.object<ThemeConfig>({
-  algolia: Joi.object({
+  algolia: Joi.object<ThemeConfigAlgolia>({
     // Docusaurus attributes
     contextualSearch: Joi.boolean().default(DEFAULT_CONFIG.contextualSearch),
     externalUrlRegex: Joi.string().optional(),
@@ -33,7 +38,9 @@ export const Schema = Joi.object<ThemeConfig>({
     }),
     apiKey: Joi.string().required(),
     indexName: Joi.string().required(),
-    searchParameters: Joi.object()
+    searchParameters: Joi.object({
+      facetFilters: FacetFiltersSchema.optional(),
+    })
       .default(DEFAULT_CONFIG.searchParameters)
       .unknown(),
     searchPagePath: Joi.alternatives()
@@ -53,15 +60,86 @@ export const Schema = Joi.object<ThemeConfig>({
       }).required(),
       to: Joi.string().required(),
     }).optional(),
+    // Ask AI configuration (DocSearch v4 only)
+    askAi: Joi.alternatives()
+      .try(
+        // Simple string format (assistantId only)
+        Joi.string(),
+        // Full configuration object
+        Joi.object({
+          indexName: Joi.string().required(),
+          apiKey: Joi.string().required(),
+          appId: Joi.string().required(),
+          assistantId: Joi.string().required(),
+          searchParameters: Joi.object({
+            facetFilters: FacetFiltersSchema.optional(),
+          }).optional(),
+        }),
+      )
+      .custom(
+        (
+          askAiInput: string | ThemeConfigAlgolia['askAi'] | undefined,
+          helpers,
+        ) => {
+          if (!askAiInput) {
+            return askAiInput;
+          }
+          const algolia: ThemeConfigAlgolia = 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,
+                    },
+                  }
+                : {}),
+            } satisfies ThemeConfigAlgolia['askAi'];
+          }
+
+          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(),
 });
 
+// TODO Docusaurus v4: remove this check when we drop DocSearch v3
+function ensureAskAISupported(themeConfig: ThemeConfig) {
+  // enforce DocsSearch v4 requirement when AskAI is configured
+  if (themeConfig.algolia.askAi && 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.',
+    );
+  }
+}
+
 export function validateThemeConfig({
   validate,
-  themeConfig,
+  themeConfig: themeConfigInput,
 }: ThemeConfigValidationContext<ThemeConfig>): ThemeConfig {
-  return validate(Schema, themeConfig);
+  const themeConfig = validate(Schema, themeConfigInput);
+  ensureAskAISupported(themeConfig);
+  return themeConfig;
 }