@docsearch/react 3.9.0 → 4.0.0-beta.0

package/dist/esm/index.d.ts

@@ -1,8 +1,9 @@
 import { BaseItem, AutocompleteState, AutocompleteContext, AutocompleteInsightsApi, AutocompleteOptions } from '@algolia/autocomplete-core';
 import { LiteClient, SearchParamsObject } from 'algoliasearch/lite';
 import React, { JSX } from 'react';
+import { Message } from '@ai-sdk/react';
 
-type ContentType = 'content' | 'lvl0' | 'lvl1' | 'lvl2' | 'lvl3' | 'lvl4' | 'lvl5' | 'lvl6';
+type ContentType = 'askAI' | 'content' | 'lvl0' | 'lvl1' | 'lvl2' | 'lvl3' | 'lvl4' | 'lvl5' | 'lvl6';
 interface DocSearchHitAttributeHighlightResult {
     value: string;
     matchLevel: 'full' | 'none' | 'partial';
@@ -35,6 +36,7 @@ interface DocSearchHitSnippetResult {
 declare type DocSearchHit = {
     objectID: string;
     content: string | null;
+    query?: string;
     url: string;
     url_without_anchor: string;
     type: ContentType;
@@ -86,11 +88,20 @@ interface DocSearchState<TItem extends BaseItem> extends AutocompleteState<TItem
     context: DocSearchContext;
 }
 
+type DocSearchTheme = 'dark' | 'light';
+
 type InternalDocSearchHit = DocSearchHit & {
     __docsearch_parent: InternalDocSearchHit | null;
 };
 
 type StoredDocSearchHit = Omit<DocSearchHit, '_highlightResult' | '_snippetResult'>;
+type StoredAskAiMessage = Message & {
+    /** Optional user feedback on this assistant message. */
+    feedback?: 'dislike' | 'like';
+};
+type StoredAskAiState = Omit<DocSearchHit, '_highlightResult' | '_snippetResult'> & {
+    messages?: StoredAskAiMessage[];
+};
 
 type DocSearchTranslations = Partial<{
     button: ButtonTranslations;
@@ -101,10 +112,33 @@ type DocSearchTransformClient = {
     addAlgoliaAgent: LiteClient['addAlgoliaAgent'];
     transporter: Pick<LiteClient['transporter'], 'algoliaAgent'>;
 };
+type DocSearchAskAi = {
+    /**
+     * The index name to use for the ask AI feature. Your assistant will search this index for relevant documents.
+     * If not provided, the index name will be used.
+     */
+    indexName?: string;
+    /**
+     * The API key to use for the ask AI feature. Your assistant will use this API key to search the index.
+     * If not provided, the API key will be used.
+     */
+    apiKey?: string;
+    /**
+     * The app ID to use for the ask AI feature. Your assistant will use this app ID to search the index.
+     * If not provided, the app ID will be used.
+     */
+    appId?: string;
+    /**
+     * The assistant ID to use for the ask AI feature.
+     */
+    assistantId: string | null;
+};
 interface DocSearchProps {
     appId: string;
     apiKey: string;
     indexName: string;
+    askAi?: DocSearchAskAi | string;
+    theme?: DocSearchTheme;
     placeholder?: string;
     searchParameters?: SearchParamsObject;
     maxResultsPerGroup?: number;
@@ -126,26 +160,60 @@ interface DocSearchProps {
     }) => string;
     insights?: AutocompleteOptions<InternalDocSearchHit>['insights'];
 }
-declare function DocSearch(props: DocSearchProps): JSX.Element;
+declare function DocSearch({ ...props }: DocSearchProps): JSX.Element;
 
 type ButtonTranslations = Partial<{
     buttonText: string;
     buttonAriaLabel: string;
 }>;
 type DocSearchButtonProps = React.ComponentProps<'button'> & {
+    theme?: DocSearchTheme;
     translations?: ButtonTranslations;
 };
 declare const DocSearchButton: React.ForwardRefExoticComponent<Omit<DocSearchButtonProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;
 
 type FooterTranslations = Partial<{
     selectText: string;
+    submitQuestionText: string;
     selectKeyAriaLabel: string;
     navigateText: string;
     navigateUpKeyAriaLabel: string;
     navigateDownKeyAriaLabel: string;
     closeText: string;
+    backToSearchText: string;
     closeKeyAriaLabel: string;
-    searchByText: string;
+    poweredByText: string;
+}>;
+
+type AskAiScreenTranslations = Partial<{
+    disclaimerText: string;
+    relatedSourcesText: string;
+    thinkingText: string;
+    copyButtonText: string;
+    copyButtonCopiedText: string;
+    copyButtonTitle: string;
+    likeButtonTitle: string;
+    dislikeButtonTitle: string;
+    thanksForFeedbackText: string;
+    preToolCallText: string;
+    duringToolCallText: string;
+    afterToolCallText: string;
+    /**
+     * Build the full jsx element for the aggregated search block.
+     * If provided, completely overrides the default english renderer.
+     */
+    aggregatedToolCallNode?: (queries: string[], onSearchQueryClick: (query: string) => void) => React.ReactNode;
+    /**
+     * Generate the list connective parts only (backwards compatibility).
+     * Receives full list of queries and should return translation parts for before/after/separators.
+     * Example: (qs) => ({ before: 'searched for ', separator: ', ', lastSeparator: ' and ', after: '' }).
+     */
+    aggregatedToolCallText?: (queries: string[]) => {
+        before?: string;
+        separator?: string;
+        lastSeparator?: string;
+        after?: string;
+    };
 }>;
 
 type ErrorScreenTranslations = Partial<{
@@ -160,6 +228,10 @@ type NoResultsScreenTranslations = Partial<{
     reportMissingResultsLinkText: string;
 }>;
 
+type ResultsScreenTranslations = Partial<{
+    askAiPlaceholder: string;
+}>;
+
 type StartScreenTranslations = Partial<{
     recentSearchesTitle: string;
     noRecentSearchesText: string;
@@ -167,20 +239,31 @@ type StartScreenTranslations = Partial<{
     removeRecentSearchButtonTitle: string;
     favoriteSearchesTitle: string;
     removeFavoriteSearchButtonTitle: string;
+    recentConversationsTitle: string;
+    removeRecentConversationButtonTitle: string;
 }>;
 
 type ScreenStateTranslations = Partial<{
     errorScreen: ErrorScreenTranslations;
     startScreen: StartScreenTranslations;
     noResultsScreen: NoResultsScreenTranslations;
+    resultsScreen: ResultsScreenTranslations;
+    askAiScreen: AskAiScreenTranslations;
 }>;
 
 type SearchBoxTranslations = Partial<{
-    resetButtonTitle: string;
-    resetButtonAriaLabel: string;
-    cancelButtonText: string;
-    cancelButtonAriaLabel: string;
+    clearButtonTitle: string;
+    clearButtonAriaLabel: string;
+    closeButtonText: string;
+    closeButtonAriaLabel: string;
+    placeholderText: string;
+    placeholderTextAskAi: string;
+    placeholderTextAskAiStreaming: string;
+    enterKeyHint: string;
+    enterKeyHintAskAi: string;
     searchInputLabel: string;
+    backToKeywordSearchButtonText: string;
+    backToKeywordSearchButtonAriaLabel: string;
 }>;
 
 type ModalTranslations = Partial<{
@@ -189,10 +272,13 @@ type ModalTranslations = Partial<{
 }> & ScreenStateTranslations;
 type DocSearchModalProps = DocSearchProps & {
     initialScrollY: number;
+    onAskAiToggle: (toggle: boolean) => void;
     onClose?: () => void;
+    isAskAiActive?: boolean;
+    canHandleAskAi?: boolean;
     translations?: ModalTranslations;
 };
-declare function DocSearchModal({ appId, apiKey, indexName, placeholder, searchParameters, maxResultsPerGroup, onClose, transformItems, hitComponent, resultsFooterComponent, navigator, initialScrollY, transformSearchClient, disableUserPersonalization, initialQuery: initialQueryFromProp, translations, getMissingResultsUrl, insights, }: DocSearchModalProps): JSX.Element;
+declare function DocSearchModal({ appId, apiKey, indexName, placeholder, askAi, searchParameters, maxResultsPerGroup, theme, onClose, transformItems, hitComponent, resultsFooterComponent, navigator, initialScrollY, transformSearchClient, disableUserPersonalization, initialQuery: initialQueryFromProp, translations, getMissingResultsUrl, insights, onAskAiToggle, isAskAiActive, canHandleAskAi, }: DocSearchModalProps): JSX.Element;
 
 interface UseDocSearchKeyboardEventsProps {
     isOpen: boolean;
@@ -200,9 +286,11 @@ interface UseDocSearchKeyboardEventsProps {
     onClose: () => void;
     onInput?: (event: KeyboardEvent) => void;
     searchButtonRef: React.RefObject<HTMLButtonElement | null>;
+    isAskAiActive: boolean;
+    onAskAiToggle: (toggle: boolean) => void;
 }
-declare function useDocSearchKeyboardEvents({ isOpen, onOpen, onClose, onInput, searchButtonRef, }: UseDocSearchKeyboardEventsProps): void;
+declare function useDocSearchKeyboardEvents({ isOpen, onOpen, onClose, onInput, isAskAiActive, onAskAiToggle, searchButtonRef, }: UseDocSearchKeyboardEventsProps): void;
 
-declare const version = "3.9.0";
+declare const version = "4.0.0-beta.0";
 
-export { type ButtonTranslations, DocSearch, DocSearchButton, type DocSearchButtonProps, type DocSearchHit, DocSearchModal, type DocSearchModalProps, type DocSearchProps, type DocSearchState, type DocSearchTransformClient, type DocSearchTranslations, type InternalDocSearchHit, type ModalTranslations, type StoredDocSearchHit, type UseDocSearchKeyboardEventsProps, useDocSearchKeyboardEvents, version };
+export { type ButtonTranslations, DocSearch, type DocSearchAskAi, DocSearchButton, type DocSearchButtonProps, type DocSearchHit, DocSearchModal, type DocSearchModalProps, type DocSearchProps, type DocSearchState, type DocSearchTheme, type DocSearchTransformClient, type DocSearchTranslations, type InternalDocSearchHit, type ModalTranslations, type StoredAskAiMessage, type StoredAskAiState, type StoredDocSearchHit, type UseDocSearchKeyboardEventsProps, useDocSearchKeyboardEvents, version };