@docsearch/js 4.4.0 → 4.5.0-beta.1

package/dist/esm/index.d.ts

@@ -2,6 +2,26 @@ import { InsightsMethodMap as InsightsMethodMap$1, InsightsClient as InsightsCli
 import React, { JSX } from 'react';
 import { JSX as JSX$1 } from 'preact';
 
+interface DocSearchModalShortcuts {
+    /**
+     * Enable/disable the Ctrl/Cmd+K shortcut to toggle the DocSearch modal.
+     *
+     * @default true
+     */
+    'Ctrl/Cmd+K'?: boolean;
+    /**
+     * Enable/disable the / shortcut to open the DocSearch modal.
+     *
+     * @default true
+     */
+    '/'?: boolean;
+}
+type InitialAskAiMessage = {
+    query: string;
+    messageId?: string;
+    suggestedQuestionId?: string;
+};
+
 type Cache = {
     /**
      * Gets the value of the given `key`.
@@ -6686,21 +6706,6 @@ declare type InsightsOption = {
 interface AutocompleteOptions<TItem extends BaseItem> extends AutocompleteOptions$1<TItem>, InsightsOption {
 }
 
-interface DocSearchModalShortcuts {
-    /**
-     * Enable/disable the Ctrl/Cmd+K shortcut to toggle the DocSearch modal.
-     *
-     * @default true
-     */
-    'Ctrl/Cmd+K'?: boolean;
-    /**
-     * Enable/disable the / shortcut to open the DocSearch modal.
-     *
-     * @default true
-     */
-    '/'?: boolean;
-}
-
 // ==================================================================================================
 // JSON Schema Draft 07
 // ==================================================================================================
@@ -8421,7 +8426,7 @@ type DocSearchAskAi = {
     /**
      * The assistant ID to use for the ask AI feature.
      */
-    assistantId: string | null;
+    assistantId: string;
     /**
      * The search parameters to use for the ask AI feature.
      */
@@ -8432,6 +8437,7 @@ type DocSearchAskAi = {
      * @default false
      */
     suggestedQuestions?: boolean;
+    useStagingEnv?: boolean;
 };
 interface DocSearchIndex {
     name: string;
@@ -8462,6 +8468,22 @@ interface DocSearchProps$1 {
      * Configuration or assistant id to enable ask ai mode. Pass a string assistant id or a full config object.
      */
     askAi?: DocSearchAskAi | string;
+    /**
+     * Intercept Ask AI requests (e.g. Submitting a prompt or selecting a suggested question).
+     *
+     * Return `true` to prevent the default modal Ask AI flow (no toggle, no sendMessage).
+     * Useful to route Ask AI into a different UI (e.g. `@docsearch/sidepanel-js`) without flicker.
+     */
+    interceptAskAiEvent?: (initialMessage: InitialAskAiMessage) => boolean | void;
+    /**
+     * **Experimental:** Whether to use Agent Studio as the chat backend.
+     *
+     * This is an experimental feature and its API may change without notice in future releases.
+     * Use with caution in production environments.
+     *
+     * @default false
+     */
+    agentStudio?: boolean;
     /**
      * Theme overrides applied to the modal and related components.
      */
@@ -8696,7 +8718,36 @@ type ModalTranslations = Partial<{
     footer: FooterTranslations;
 }> & ScreenStateTranslations;
 
-type DocSearchProps = DocSearchProps$1 & {
+/**
+ * Instance returned by docsearch() for programmatic control.
+ */
+interface DocSearchInstance {
+    /** Returns true once the component is mounted and ready. */
+    readonly isReady: boolean;
+    /** Returns true if the modal is currently open. */
+    readonly isOpen: boolean;
+    /** Opens the search modal. */
+    open(): void;
+    /** Closes the search modal. */
+    close(): void;
+    /** Opens Ask AI mode (modal). */
+    openAskAi(initialMessage?: InitialAskAiMessage): void;
+    /** Unmounts the DocSearch component and cleans up. */
+    destroy(): void;
+}
+/**
+ * Lifecycle callbacks for the DocSearch instance.
+ */
+interface DocSearchCallbacks {
+    /** Called once DocSearch is mounted and ready for interaction. */
+    onReady?: () => void;
+    /** Called when the modal opens. */
+    onOpen?: () => void;
+    /** Called when the modal closes. */
+    onClose?: () => void;
+    interceptAskAiEvent?: (initialMessage: InitialAskAiMessage) => boolean | void;
+}
+type DocSearchProps = DocSearchCallbacks & Omit<DocSearchProps$1, 'onSidepanelClose' | 'onSidepanelOpen'> & {
     container: HTMLElement | string;
     environment?: typeof window;
 };
@@ -8704,7 +8755,7 @@ declare const html: (strings: TemplateStringsArray, ...values: unknown[]) => JSX
 type TemplateHelpers = Record<string, unknown> & {
     html: typeof html;
 };
-declare function docsearch(allProps: DocSearchProps): () => void;
+declare function docsearch(allProps: DocSearchProps): DocSearchInstance;
 
 export { docsearch as default };
-export type { DocSearchProps, TemplateHelpers };
+export type { DocSearchCallbacks, DocSearchInstance, DocSearchProps, TemplateHelpers };