@ckeditor/ckeditor5-ai 48.8.1-alpha.4 → 49.0.0-alpha.1

package/dist/aichat/aichatui.d.ts

@@ -1,365 +1,389 @@
 /**
- * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
- */
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
+*/
 /**
- * @module ai/aichat/aichatui
- */
-import { type Context, type Editor, ContextPlugin } from '@ckeditor/ckeditor5-core';
-import { AITabs } from '../aitabs/aitabs.js';
-import { type AIAddContextOptionsState, type AIContextProvider, type AIContextResource, type AIContextResourceState } from './model/aichatcontext.js';
-import { type AIContextItem } from '../aicore/model/aicontext.js';
-import { type Document } from '../aicore/utils/htmlparser.js';
-import { type AICapabilitiesConfig } from '../aicore/model/aicapabilities.js';
-import { type AIReply, type AIReplyChangeGroupState } from '../aicore/model/aireply.js';
-import { type AISuggestionContentPartDefinition } from '../aicore/utils/getsuggestionpartsfromreply.js';
-import { type AIChatConversationInitializedEvent } from './model/aichatconversation.js';
-import { type AIModelData, type AISource } from '../aicore/aiconnector.js';
-import { type AIChatInteraction } from './model/aichatinteraction.js';
-import { type AIContentRenderingStrategy } from '../aicore/ui/suggestioncontainer/aisuggestionstreamablecontentview.js';
-import '../../theme/aichat/aichat.css';
-import { type AIChatFeedCustomElementView } from './ui/feed/aichatfeedcustomelementview.js';
+* @module ai/aichat/aichatui
+*/
+import { type Context, type Editor, ContextPlugin, type PluginDependenciesOf } from "@ckeditor/ckeditor5-core";
+import { AITabs } from "../aitabs/aitabs.js";
+import { type AIAddContextOptionsState, type AIContextProvider, type AIContextResource, type AIContextResourceState } from "./model/aichatcontext.js";
+import { type AIContextItem } from "../aicore/model/aicontext.js";
+import { type Document } from "../aicore/utils/htmlparser.js";
+import { type AICapabilitiesConfig } from "../aicore/model/aicapabilities.js";
+import { type AIChatInputPaste } from "./utils/resolvepaste.js";
+import { type AIReply, type AIReplyChangeGroupState, type AIReplyChangeGroupOutdatedReason } from "../aicore/model/aireply.js";
+import { type AISuggestionContentPartDefinition } from "../aicore/utils/getsuggestionpartsfromreply.js";
+import { type AISuggestionGating } from "../aicore/ui/suggestioncontainer/aisuggestionbodyview.js";
+import { type AIModelData, type AISource } from "../aicore/aiconnector.js";
+import { type AIChatInteraction } from "./model/aichatinteraction.js";
+import { type AIContentRenderingStrategy } from "../aicore/ui/suggestioncontainer/aisuggestionstreamablecontentview.js";
+import { type AIChatFeedCustomElementView } from "./ui/feed/aichatfeedcustomelementview.js";
+import { type AIChatFeedSkeletonType } from "./ui/aichatfeedview.js";
 export declare class AIChatUI extends ContextPlugin {
-    /**
-     * @inheritDoc
-     */
-    static get requires(): readonly [typeof AITabs];
-    /**
-     * @inheritDoc
-     */
-    static get pluginName(): "AIChatUI";
-    /**
-     * @inheritDoc
-     */
-    static get isOfficialPlugin(): true;
-    /**
-     * @inheritDoc
-     */
-    static get isPremiumPlugin(): true;
-    /**
-     * The busy state of the UI.
-     *
-     * It is set to `true` when there are AI response being streamed or rendered.
-     *
-     * @observable
-     */
-    isBusy: boolean;
-    /**
-     * Indicates if the active model is available.
-     *
-     * @observable
-     */
-    isModelAvailable: boolean;
-    /**
-     * @inheritDoc
-     */
-    constructor(context: Context | Editor);
-    destroy(): void;
-    /**
-     * Creates a new conversation by greeting the user.
-     */
-    createConversation(data: AIChatConversationInitializedEvent['args'][0]): void;
-    /**
-     * Adds a generic message to the chat feed.
-     */
-    addFeedItemStaticMessage({ id, staticMessage }: {
-        id: string;
-        staticMessage?: string;
-    }): Promise<void>;
-    /**
-     * Adds a user message to the chat feed.
-     */
-    addFeedItemUserMessage(interaction: AIChatInteraction): Promise<void>;
-    /**
-     * Adds an error message to the chat feed.
-     */
-    addFeedItemError({ errorMessage, id }: {
-        errorMessage: string;
-        id: string;
-    }): Promise<void>;
-    /**
-     * Adds an AI reply to the chat feed.
-     */
-    addFeedItemAIReply(reply: AIReply): Promise<void>;
-    /**
-     * Adds an AI suggestion reply to the chat feed.
-     */
-    addFeedItemAISuggestion(reply: AIReply): Promise<void>;
-    /**
-     * Adds an interaction header to the chat feed.
-     */
-    addFeedInteractionHeader(interaction: AIChatInteraction, capabilities: AICapabilitiesConfig): Promise<void>;
-    /**
-     * Adds a custom element to the chat feed.
-     */
-    addFeedItemCustomElement(element: HTMLElement | string, id: string): Promise<AIChatFeedCustomElementView>;
-    /**
-     * Removes an item from the feed.
-     */
-    removeFeedItem(id: string): void;
-    /**
-     * Checks if an item exists in the feed.
-     */
-    hasFeedItem(id: string): boolean;
-    /**
-     * Updates the visibility of the interaction header in the chat feed.
-     */
-    updateFeedInteractionHeader(options: {
-        isVisible: boolean;
-        id: string;
-    }): void;
-    /**
-     * Updates the content of an AI reply in the chat feed.
-     */
-    updateFeedItemAIReplyContent(options: {
-        id: string;
-        parsedContent: Document;
-        renderingStrategy?: AIContentRenderingStrategy;
-        isDone?: boolean;
-    }): Promise<void>;
-    updateFeedItemAIReplySources(id: string, sources: Array<AISource>): void;
-    /**
-     * Updates the content of an AI suggestion reply in the chat feed.
-     */
-    updateFeedItemAIReplySuggestionContent(options: {
-        id: string;
-        parts: Array<AISuggestionContentPartDefinition>;
-        isDone?: boolean;
-        skipLoadingEffects?: boolean;
-    }): Promise<void>;
-    /**
-     * Updates the state of a content part by its index.
-     */
-    updateFeedItemAIReplySuggestionPartState(options: {
-        id: string;
-        index: number;
-        state: AIReplyChangeGroupState;
-    }): void;
-    /**
-     * Sets the part active or not (active parts are those currently previewed in a dialog by the user).
-     */
-    setFeedItemAIReplySuggestionPartActive(options: {
-        id: string;
-        index: number;
-        isActive: boolean;
-    }): void;
-    /**
-     * Removes an interaction from the chat feed. Interaction is a user message + one or more AI replies.
-     */
-    removeFeedInteraction(interactionId: string): void;
-    /**
-     * Starts a new interaction processing in the UI and marks the UI as busy.
-     */
-    startInteraction(): void;
-    /**
-     * Handles the user stopping the interaction. It terminates all scheduled UI update promises and unlocks the UI
-     * immediately.
-     */
-    stopInteraction(interaction: AIChatInteraction): void;
-    /**
-     * Handles the interaction finishing due to lack of data to process (or an error). Waits for all pending UI
-     * updates to finish, then unlocks the UI.
-     */
-    finishInteraction(): Promise<void>;
-    /**
-     * Adds an item chip to the current context list.
-     */
-    addContextItem(contextItem: AIContextItem, isLoading: boolean): void;
-    /**
-     * Removes an item from the context as chip.
-     */
-    removeContextItem(id: string): void;
-    /**
-     * Sets the loading state of an item chip in the current context list.
-     */
-    setContextItemLoading(uiId: string, isLoading: boolean): void;
-    /**
-     * Sets the upload in progress state.
-     */
-    setIsUploadInProgress(isUploadInProgress: boolean): void;
-    /**
-     * Sets the conversation context chips.
-     */
-    setConversationContext(contextItems: Array<AIContextItem>): void;
-    /**
-     * Removes all chips from the current context list.
-     */
-    clearPendingContextUI(): void;
-    /**
-     * Clears all chips from the conversation context list.
-     */
-    clearConversationContextUI(): void;
-    /**
-     * Updates the state of a specific resource in the balloon views.
-     */
-    updateResourceState(sourceId: string, resourceId: string, isInContext: boolean): void;
-    /**
-     * Resets the message input in the controls view.
-     */
-    resetMessageInput(): void;
-    /**
-     * Sets the add context options in the UI.
-     */
-    setAddContextOptions(options: AIAddContextOptionsState): void;
-    /**
-     * Updates the capabilities of the AI chat in the UI.
-     */
-    updateCapabilities(capabilities: AICapabilitiesConfig): void;
-    /**
-     * Updates selected AI model in the controls view.
-     */
-    setSelectedModel(model: AIModelData | null, isDisabled?: boolean): void;
-    /**
-     * Sets the rendering strategy for the feed items. Streaming is default and uses HTMLStreamer to stream the content.
-     *
-     * Static works out for messages that must appear instantly.
-     */
-    setFeedItemRenderingStrategy(strategy: 'streaming' | 'static'): void;
-    /**
-     * Toggles the loading skeleton in the chat feed.
-     */
-    toggleLoadingSkeleton(isLoading: boolean): void;
-    /**
-     * Resets the conversation title to the default value.
-     */
-    resetConversationTitle(): void;
-    /**
-     * Sets the title for the conversation.
-     *
-     * @param title The new title of the conversation.
-     * @param shouldAnimate Whether the title change should be animated. Defaults to `false`.
-     */
-    setConversationTitle(title: string, shouldAnimate?: boolean): void;
-    /**
-     * Sets the loading message of the chat feed.
-     */
-    setLoadingMessage(message: string): void;
-    /**
-     * Clears the loading message of the chat feed.
-     */
-    clearLoadingMessage(): void;
-    /**
-     * Populates a source resource balloon with loaded resources.
-     */
-    populateSourceResourceBalloon(sourceId: string, source: AIContextProvider, resources: Array<AIContextResourceState>, uid: string): void;
-    /**
-     * Closes the source resource balloon and cleans up its state.
-     */
-    closeSourceResourceBalloon(sourceId: string): void;
-    /**
-     * Sets the value of the prompt input.
-     */
-    setPromptInputValue(value: string): void;
-    /**
-     * Focuses the prompt input.
-     */
-    focusPromptInput(useHighlight?: boolean): void;
-    scrollFeedToSuggestion(replyId: string, partIndex: number): void;
-    startAutoScroll(options?: {
-        smooth?: boolean;
-    }): void;
-    disableControls(): void;
-    enableControls(): void;
+	/**
+	* @inheritDoc
+	*/
+	static get requires(): PluginDependenciesOf<[AITabs]>;
+	/**
+	* @inheritDoc
+	*/
+	static get pluginName(): "AIChatUI";
+	/**
+	* @inheritDoc
+	*/
+	static override get isOfficialPlugin(): true;
+	/**
+	* @inheritDoc
+	*/
+	static override get isPremiumPlugin(): true;
+	/**
+	* The busy state of the UI.
+	*
+	* It is set to `true` when the UI is busy for any reason, e.g.:
+	* - The AI response is still being streamed or rendered.
+	* - A whole conversation from history is still being loaded or rendered.
+	*
+	* @observable
+	*/
+	isBusy: boolean;
+	/**
+	* Indicates if the active model is available.
+	*
+	* @observable
+	*/
+	isModelAvailable: boolean;
+	/**
+	* @observable
+	*/
+	isChatStreaming: boolean;
+	/**
+	* @inheritDoc
+	*/
+	constructor(context: Context | Editor);
+	override destroy(): void;
+	/**
+	* Creates a new conversation by greeting the user.
+	*/
+	createConversation({ availableModels }: {
+		availableModels: Array<AIModelData>;
+	}): void;
+	/**
+	* Adds a generic message to the chat feed.
+	*/
+	addFeedItemStaticMessage({ id, staticMessage }: {
+		id: string;
+		staticMessage?: string;
+	}): Promise<void>;
+	/**
+	* Adds a user message to the chat feed.
+	*/
+	addFeedItemUserMessage(interaction: AIChatInteraction): Promise<void>;
+	/**
+	* Adds an error message to the chat feed.
+	*/
+	addFeedItemError({ errorMessage, id }: {
+		errorMessage: string;
+		id: string;
+	}): Promise<void>;
+	/**
+	* Adds an AI reply to the chat feed.
+	*/
+	addFeedItemAIReply(reply: AIReply): Promise<void>;
+	/**
+	* Adds an AI suggestion reply to the chat feed.
+	*/
+	addFeedItemAISuggestion(reply: AIReply): Promise<void>;
+	/**
+	* Adds an interaction header to the chat feed.
+	*/
+	addFeedInteractionHeader(interaction: AIChatInteraction, capabilities: AICapabilitiesConfig): Promise<void>;
+	/**
+	* Adds a custom element to the chat feed.
+	*/
+	addFeedItemCustomElement(element: HTMLElement | string, id: string): Promise<AIChatFeedCustomElementView>;
+	/**
+	* Removes an item from the feed.
+	*/
+	removeFeedItem(id: string): void;
+	/**
+	* Checks if an item exists in the feed.
+	*/
+	hasFeedItem(id: string): boolean;
+	/**
+	* Updates the visibility of the interaction header in the chat feed.
+	*/
+	updateFeedInteractionHeader(options: {
+		isVisible: boolean;
+		id: string;
+	}): void;
+	/**
+	* Updates the content of an AI reply in the chat feed.
+	*/
+	updateFeedItemAIReplyContent(options: {
+		id: string;
+		parsedContent: Document;
+		renderingStrategy?: AIContentRenderingStrategy;
+		isDone?: boolean;
+	}): Promise<void>;
+	updateFeedItemAIReplySources(id: string, sources: Array<AISource>): void;
+	/**
+	* Updates the content of an AI suggestion reply in the chat feed.
+	*/
+	updateFeedItemAIReplySuggestionContent(options: {
+		id: string;
+		parts: Array<AISuggestionContentPartDefinition>;
+		isDone?: boolean;
+		skipLoadingEffects?: boolean;
+	}): Promise<void>;
+	/**
+	* Updates the state of a content part by its index.
+	*/
+	updateFeedItemAIReplySuggestionPartState(options: {
+		id: string;
+		index: number;
+		state: AIReplyChangeGroupState;
+		outdatedReason?: AIReplyChangeGroupOutdatedReason;
+	}): void;
+	/**
+	* Applies the gating state to a suggestion reply's views.
+	*/
+	setSuggestionGating(replyId: string, gating: AISuggestionGating): void;
+	/**
+	* Sets the part active or not (active parts are those currently previewed in a dialog by the user).
+	*/
+	setFeedItemAIReplySuggestionPartActive(options: {
+		id: string;
+		index: number;
+		isActive: boolean;
+	}): void;
+	/**
+	* Returns the number a suggestion part is displayed under in the chat feed.
+	*/
+	getFeedItemAIReplySuggestionPartUIIndex(options: {
+		id: string;
+		index: number;
+	}): number | null;
+	/**
+	* Removes an interaction from the chat feed. Interaction is a user message + one or more AI replies.
+	*/
+	removeFeedInteraction(interactionId: string): void;
+	/**
+	* Starts a new interaction processing in the UI and marks the UI as busy.
+	*/
+	startInteraction(): void;
+	/**
+	* Handles the user stopping the interaction. It terminates all scheduled UI update promises and unlocks the UI
+	* immediately.
+	*/
+	stopInteraction(interaction?: AIChatInteraction): void;
+	/**
+	* Handles the interaction finishing due to lack of data to process (or an error). Waits for all pending UI
+	* updates to finish, then unlocks the UI.
+	*/
+	finishInteraction(): Promise<void>;
+	/**
+	* Adds an item chip to the current context list.
+	*/
+	addContextItem(contextItem: AIContextItem, isLoading: boolean): void;
+	/**
+	* Removes an item from the context as chip.
+	*/
+	removeContextItem(id: string): void;
+	/**
+	* Sets the loading state of an item chip in the current context list.
+	*/
+	setContextItemLoading(uiId: string, isLoading: boolean): void;
+	/**
+	* Sets the upload in progress state.
+	*/
+	setIsUploadInProgress(isUploadInProgress: boolean): void;
+	/**
+	* Sets the conversation context chips.
+	*/
+	setConversationContext(contextItems: Array<AIContextItem>): void;
+	/**
+	* Removes all chips from the current context list.
+	*/
+	clearPendingContextUI(): void;
+	/**
+	* Clears all chips from the conversation context list.
+	*/
+	clearConversationContextUI(): void;
+	/**
+	* Updates the state of a specific resource in the balloon views.
+	*/
+	updateResourceState(sourceId: string, resourceId: string, isInContext: boolean): void;
+	/**
+	* Resets the message input in the controls view.
+	*/
+	resetMessageInput(): void;
+	/**
+	* Sets the add context options in the UI.
+	*/
+	setAddContextOptions(options: AIAddContextOptionsState): void;
+	/**
+	* Updates the capabilities of the AI chat in the UI.
+	*/
+	updateCapabilities(capabilities: AICapabilitiesConfig): void;
+	/**
+	* Updates selected AI model in the controls view.
+	*/
+	setSelectedModel(model: AIModelData | null, isDisabled?: boolean): void;
+	/**
+	* Sets the rendering strategy for the feed items. Streaming is default and uses HTMLStreamer to stream the content.
+	*
+	* Static works out for messages that must appear instantly.
+	*/
+	setFeedItemRenderingStrategy(strategy: "streaming" | "static"): void;
+	/**
+	* Toggles the loading skeleton in the chat feed.
+	*
+	* @param isLoading Whether the skeleton should be visible.
+	* @param type Which skeleton the call refers to.
+	*/
+	toggleLoadingSkeleton(isLoading: boolean, type?: AIChatFeedSkeletonType): void;
+	/**
+	* Resets the conversation title to the default value.
+	*/
+	resetConversationTitle(): void;
+	/**
+	* Empties the conversation title used for loading state.
+	*/
+	emptyConversationTitle(): void;
+	/**
+	* Sets the title for the conversation.
+	*
+	* @param title The new title of the conversation.
+	* @param shouldAnimate Whether the title change should be animated. Defaults to `false`.
+	*/
+	setConversationTitle(title: string, shouldAnimate?: boolean): void;
+	/**
+	* Sets the loading message of the chat feed.
+	*/
+	setLoadingMessage(message: string): void;
+	/**
+	* Clears the loading message of the chat feed.
+	*/
+	clearLoadingMessage(): void;
+	/**
+	* Populates a source resource balloon with loaded resources.
+	*/
+	populateSourceResourceBalloon(sourceId: string, source: AIContextProvider, resources: Array<AIContextResourceState>, uid: string): void;
+	/**
+	* Closes the source resource balloon and cleans up its state.
+	*/
+	closeSourceResourceBalloon(sourceId: string): void;
+	/**
+	* Sets the value of the prompt input.
+	*/
+	setPromptInputValue(value: string): void;
+	/**
+	* Focuses the prompt input.
+	*/
+	focusPromptInput(useHighlight?: boolean): void;
+	scrollFeedToSuggestion(replyId: string, partIndex: number): void;
+	startAutoScroll(options?: {
+		smooth?: boolean;
+	}): void;
+	stopAutoScroll(): void;
+	disableControls(): void;
+	enableControls(): void;
+	toggleConversationLoading(updatedIsBusy: boolean): void;
 }
 /**
- * An event fired when the user starts a new conversation.
- */
+* An event fired when the user starts a new conversation.
+*/
 export type AIChatUIStartConversationEvent = {
-    name: 'startConversation';
-    args: [];
+	name: "startConversation";
+	args: [];
 };
 /**
- * An event fired when the user sends a message to the AI.
- */
+* An event fired when the user sends a message to the AI.
+*/
 export type AIChatUISendUserMessageEvent = {
-    name: 'sendUserMessage';
-    args: [
-        string
-    ];
+	name: "sendUserMessage";
+	args: [string];
 };
 /**
- * An event fired when the user wants to abort the current interaction with the AI.
- */
+* An event fired when the user wants to abort the current interaction with the AI.
+*/
 export type AIChatUIAbortPromptStreamEvent = {
-    name: 'abortPromptStream';
-    args: [];
+	name: "abortPromptStream";
+	args: [];
 };
 /**
- * An event fired when the user wants to add a document to the context.
- */
+* An event fired when the user wants to add a document to the context.
+*/
 export type AIChatUIAddDocumentToContextEvent = {
-    name: 'addDocumentToContext';
-    args: [];
+	name: "addDocumentToContext";
+	args: [];
 };
 /**
- * An event fired when the user wants to add a file to the context.
- */
+* An event fired when the user wants to add a file to the context.
+*/
 export type AIChatUIAddFileToContextEvent = {
-    name: 'addFileToContext';
-    args: [
-        Array<File>
-    ];
+	name: "addFileToContext";
+	args: [Array<File>];
 };
 /**
- * An event fired when the user wants to add a URL to the context.
- */
+* An event fired when the user wants to add a URL to the context.
+*/
 export type AIChatUIAddUrlToContextEvent = {
-    name: 'addUrlToContext';
-    args: [
-        string
-    ];
+	name: "addUrlToContext";
+	args: [string];
 };
 /**
- * An event fired when the user wants to execute a custom item callback.
- */
+* An event fired when the user pastes content into the prompt input. Carries a DOM-free
+* payload that the controller classifies and dispatches.
+*/
+export type AIChatUIPromptInputPasteEvent = {
+	name: "promptInputPaste";
+	args: [paste: AIChatInputPaste];
+};
+/**
+* An event fired when the user wants to execute a custom item callback.
+*/
 export type AIChatUIExecuteCustomItemCallbackEvent = {
-    name: 'executeCustomItemCallback';
-    args: [
-        {
-            id: string;
-            callback: (editor: Editor) => void;
-        }
-    ];
+	name: "executeCustomItemCallback";
+	args: [{
+		id: string;
+		callback: (editor: Editor) => void;
+	}];
 };
 /**
- * An event fired when the user wants to add a resource to the context.
- */
+* An event fired when the user wants to add a resource to the context.
+*/
 export type AIChatUIAddResourceToContextEvent = {
-    name: 'addResourceToContext';
-    args: [
-        {
-            source: AIContextProvider;
-            resource: AIContextResource;
-        }
-    ];
+	name: "addResourceToContext";
+	args: [{
+		source: AIContextProvider;
+		resource: AIContextResource;
+	}];
 };
 /**
- * An event fired when the user wants to remove a context item.
- */
+* An event fired when the user wants to remove a context item.
+*/
 export type AIChatUIRemoveContextItemEvent = {
-    name: 'removeContextItem';
-    args: [
-        string
-    ];
+	name: "removeContextItem";
+	args: [string];
 };
 /**
- * An event fired when the user wants to load resources from a source provider.
- */
+* An event fired when the user wants to load resources from a source provider.
+*/
 export type AIChatUILoadSourceResourcesEvent = {
-    name: 'loadSourceResources';
-    args: [
-        {
-            sourceId: string;
-            query: string;
-            uid: string;
-        }
-    ];
+	name: "loadSourceResources";
+	args: [{
+		sourceId: string;
+		query: string;
+		uid: string;
+	}];
 };
 /**
- * An event fired when a new conversation is created, the chat feed is empty and the welcome message has been
- * displayed.
- */
+* An event fired when a new conversation is created, the chat feed is empty and the welcome message has been
+* displayed.
+*/
 export type AIChatUIConversationCreatedEvent = {
-    name: 'conversationCreated';
-    args: [];
+	name: "conversationCreated";
+	args: [];
 };