@ckeditor/ckeditor5-ai 48.8.1-alpha.3 → 49.0.0-alpha.0

package/dist/aichat/ui/aichatfeedview.d.ts

@@ -1,135 +1,152 @@
 /**
- * @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/ui/aichatfeedview
- */
-import { type Locale } from '@ckeditor/ckeditor5-utils';
-import { View, type ViewCollection, type BodyCollection } from '@ckeditor/ckeditor5-ui';
-import { type AIChatFeedItemView } from './feed/aichatfeeditemview.js';
-import { type AIContentRenderingStrategy } from '../../aicore/ui/suggestioncontainer/aisuggestionstreamablecontentview.js';
-import { type Document } from '../../aicore/utils/htmlparser.js';
-import { AIChatFeedSuggestionItemView } from './feed/aichatfeedsuggestionitemview.js';
-import { AIChatFeedReplyItemView } from './feed/aichatfeedreplyitemview.js';
-import { AIChatFeedUserMessageItemView } from './feed/aichatfeedusermessageitem.js';
-import { AIChatFeedErrorItemView } from './feed/aichatfeederroritemview.js';
-import { AIChatFeedInteractionHeaderView } from './feed/aichatfeedinteractionheaderview.js';
-import { type AISuggestionContentPartDefinition } from '../../aicore/utils/getsuggestionpartsfromreply.js';
-import { AIChatFeedCustomElementView } from './feed/aichatfeedcustomelementview.js';
-import { type AIReplyChangeGroupState } from '../../aicore/model/aireply.js';
-import { type AISource } from '../../aicore/aiconnector.js';
-import '../../../theme/aichat/aichatfeed.css';
+* @module ai/aichat/ui/aichatfeedview
+*/
+import { type Locale } from "@ckeditor/ckeditor5-utils";
+import { View, type ViewCollection, type BodyCollection } from "@ckeditor/ckeditor5-ui";
+import { type AIChatFeedItemView } from "./feed/aichatfeeditemview.js";
+import { type AIContentRenderingStrategy } from "../../aicore/ui/suggestioncontainer/aisuggestionstreamablecontentview.js";
+import { type Document } from "../../aicore/utils/htmlparser.js";
+import { AIChatFeedSuggestionItemView } from "./feed/aichatfeedsuggestionitemview.js";
+import { AIChatFeedReplyItemView } from "./feed/aichatfeedreplyitemview.js";
+import { AIChatFeedUserMessageItemView } from "./feed/aichatfeedusermessageitem.js";
+import { AIChatFeedErrorItemView } from "./feed/aichatfeederroritemview.js";
+import { AIChatFeedInteractionHeaderView } from "./feed/aichatfeedinteractionheaderview.js";
+import { type AISuggestionContentPartDefinition } from "../../aicore/utils/getsuggestionpartsfromreply.js";
+import { AIChatFeedCustomElementView } from "./feed/aichatfeedcustomelementview.js";
+import { type AIReplyChangeGroupState, type AIReplyChangeGroupOutdatedReason } from "../../aicore/model/aireply.js";
+import { type AISource } from "../../aicore/aiconnector.js";
+import { type AISuggestionGating } from "../../aicore/ui/suggestioncontainer/aisuggestionbodyview.js";
 /**
- * A view that displays the chat feed with various items.
- */
+* A view that displays the chat feed with various items.
+*/
 export declare class AIChatFeedView extends View {
-    /**
-     * A collection of feed items.
-     */
-    readonly children: ViewCollection<AIChatFeedItemView>;
-    /**
-     * The loading message displayed when the feed is processing a response.
-     *
-     * When set, it gets displayed together with a loader spinner.
-     *
-     * @observable
-     */
-    loadingMessage: string;
-    /**
-     * @observable
-     */
-    isTrackChangesOn: boolean;
-    /**
-     * @inheritDoc
-     */
-    constructor(locale: Locale, bodyCollection: BodyCollection);
-    render(): void;
-    destroy(): void;
-    /**
-     * Removes all items from the feed.
-     */
-    clear(): void;
-    /**
-     * Adds a new item to the feed.
-     */
-    addItem<T extends keyof ChatFeedAddItemTypesInstances>(itemType: T, options: ChatFeedAddItemTypesInstances[T]['options']): ChatFeedAddItemTypesInstances[T];
-    /**
-     * Updates the content of an item in the feed.
-     *
-     * **Note**: The content is updated (streamed) asynchronously.
-     */
-    updateReplyItem({ id, parsedContent, renderingStrategy, abortSignal }: {
-        id: string;
-        parsedContent: Document;
-        renderingStrategy: AIContentRenderingStrategy;
-        abortSignal: AbortSignal;
-    }): Promise<void>;
-    updateWebSources(id: string, sources: Array<AISource>): Promise<void>;
-    updateSuggestionItem({ id, parts, abortSignal, skipLoadingEffects }: {
-        id: string;
-        parts: Array<AISuggestionContentPartDefinition>;
-        abortSignal: AbortSignal;
-        skipLoadingEffects?: boolean;
-    }): Promise<void>;
-    updateSuggestionPartState({ id, index, state }: {
-        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).
-     */
-    setSuggestionPartActive({ id, index, isActive }: {
-        id: string;
-        index: number;
-        isActive: boolean;
-    }): void;
-    /**
-     * Marks an item as done.
-     *
-     * **Note**: Marking the item as done cleans up the streaming animations.
-     */
-    markItemAsDone(id: string): void;
-    /**
-     * Returns all item ids.
-     */
-    getItemIds(): Array<string>;
-    /**
-     * Removes an item from the feed.
-     */
-    removeItem(id: string): void;
-    /**
-     * Checks if an item exists in the feed.
-     */
-    hasItem(id: string): boolean;
-    scrollToSuggestion(replyId: string, partIndex: number): void;
-    /**
-     * Sets the loading message of the chat feed.
-     */
-    setLoadingMessage(message: string): void;
-    /**
-     * Toggles the loading skeleton in the feed.
-     */
-    toggleLoadingSkeleton(isLoading: boolean): void;
-    /**
-     * Starts the auto-scrolling of the feed.
-     *
-     * @param options.smooth When `false`, the scroll jumps instantly instead of animating. Defaults to `true`.
-     */
-    startAutoScroll(options?: {
-        smooth?: boolean;
-    }): void;
-    /**
-     * Stops the auto-scrolling of the feed.
-     */
-    stopAutoScroll(): void;
+	/**
+	* A collection of feed items.
+	*/
+	readonly children: ViewCollection<AIChatFeedItemView>;
+	/**
+	* The loading message displayed when the feed is processing a response.
+	*
+	* When set, it gets displayed together with a loader spinner.
+	*
+	* @observable
+	*/
+	loadingMessage: string;
+	/**
+	* @observable
+	*/
+	isTrackChangesOn: boolean;
+	/**
+	* @inheritDoc
+	*/
+	constructor(locale: Locale, bodyCollection: BodyCollection);
+	override render(): void;
+	override destroy(): void;
+	/**
+	* Removes all items from the feed.
+	*/
+	clear(): void;
+	/**
+	* Adds a new item to the feed.
+	*/
+	addItem<T extends keyof ChatFeedAddItemTypesInstances>(itemType: T, options: ChatFeedAddItemTypesInstances[T]["options"]): ChatFeedAddItemTypesInstances[T];
+	/**
+	* Updates the content of an item in the feed.
+	*
+	* **Note**: The content is updated (streamed) asynchronously.
+	*/
+	updateReplyItem({ id, parsedContent, renderingStrategy, abortSignal }: {
+		id: string;
+		parsedContent: Document;
+		renderingStrategy: AIContentRenderingStrategy;
+		abortSignal: AbortSignal;
+	}): Promise<void>;
+	updateWebSources(id: string, sources: Array<AISource>): Promise<void>;
+	updateSuggestionItem({ id, parts, abortSignal, skipLoadingEffects }: {
+		id: string;
+		parts: Array<AISuggestionContentPartDefinition>;
+		abortSignal: AbortSignal;
+		skipLoadingEffects?: boolean;
+	}): Promise<void>;
+	updateSuggestionPartState({ id, index, state, outdatedReason }: {
+		id: string;
+		index: number;
+		state: AIReplyChangeGroupState;
+		outdatedReason?: AIReplyChangeGroupOutdatedReason;
+	}): void;
+	updateSuggestionGating(replyId: string, gating: AISuggestionGating): void;
+	/**
+	* Returns the number a suggestion part is displayed under in the feed.
+	*/
+	getSuggestionPartUIIndex({ id, index }: {
+		id: string;
+		index: number;
+	}): number | null;
+	/**
+	* Sets the part active or not (active parts are those currently previewed in a dialog by the user).
+	*/
+	setSuggestionPartActive({ id, index, isActive }: {
+		id: string;
+		index: number;
+		isActive: boolean;
+	}): void;
+	/**
+	* Marks an item as done.
+	*
+	* **Note**: Marking the item as done cleans up the streaming animations.
+	*/
+	markItemAsDone(id: string): void;
+	/**
+	* Returns all item ids.
+	*/
+	getItemIds(): Array<string>;
+	/**
+	* Removes an item from the feed.
+	*/
+	removeItem(id: string): void;
+	/**
+	* Checks if an item exists in the feed.
+	*/
+	hasItem(id: string): boolean;
+	scrollToSuggestion(replyId: string, partIndex: number): void;
+	/**
+	* Sets the loading message of the chat feed.
+	*/
+	setLoadingMessage(message: string): void;
+	/**
+	* Toggles the loading skeleton in the feed.
+	*
+	* @param isLoading Whether the skeleton should be visible.
+	* @param type Which skeleton the call refers to.
+	*/
+	toggleLoadingSkeleton(isLoading: boolean, type?: AIChatFeedSkeletonType): void;
+	/**
+	* Starts the auto-scrolling of the feed.
+	*
+	* @param options.smooth When `false`, the scroll jumps instantly instead of animating. Defaults to `true`.
+	*/
+	startAutoScroll(options?: {
+		smooth?: boolean;
+	}): void;
+	/**
+	* Stops the auto-scrolling of the feed.
+	*/
+	stopAutoScroll(): void;
 }
 export interface ChatFeedAddItemTypesInstances {
-    'interaction-header': AIChatFeedInteractionHeaderView;
-    'ai-reply': AIChatFeedReplyItemView;
-    'ai-suggestion-reply': AIChatFeedSuggestionItemView;
-    'user-message': AIChatFeedUserMessageItemView;
-    'error-message': AIChatFeedErrorItemView;
-    'custom-element': AIChatFeedCustomElementView;
+	"interaction-header": AIChatFeedInteractionHeaderView;
+	"ai-reply": AIChatFeedReplyItemView;
+	"ai-suggestion-reply": AIChatFeedSuggestionItemView;
+	"user-message": AIChatFeedUserMessageItemView;
+	"error-message": AIChatFeedErrorItemView;
+	"custom-element": AIChatFeedCustomElementView;
 }
+/**
+* Which loading skeleton the chat feed shows: the initial one, awaiting the welcome message, or the one
+* awaiting a conversation loaded from history.
+*/
+export type AIChatFeedSkeletonType = "init" | "conversation";

package/dist/aichat/ui/aichatview.d.ts

@@ -1,45 +1,47 @@
 /**
- * @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/ui/aichatview
- */
-import { type Locale } from '@ckeditor/ckeditor5-utils';
-import { View } from '@ckeditor/ckeditor5-ui';
-import { AIChatFeedView } from './aichatfeedview.js';
-import { AIChatControlsView } from './aichatcontrolsview.js';
-import { AIHeaderView } from '../../aicore/ui/aiheaderview.js';
-import { AIDisclaimerView } from '../../aicore/ui/aidisclaimerview.js';
-import { type AIContextProvider, type AIContextResourceState } from '../../aichat/model/aichatcontext.js';
-import '../../../theme/common/ainotification.css';
-import '../../../theme/common/aibutton.css';
-import '../../../theme/common/aicolor.css';
-import '../../../theme/common/aitrackchanges.css';
+* @module ai/aichat/ui/aichatview
+*/
+import { type Locale } from "@ckeditor/ckeditor5-utils";
+import { View, type BodyCollection } from "@ckeditor/ckeditor5-ui";
+import { AIChatFeedView } from "./aichatfeedview.js";
+import { AIChatControlsView } from "./aichatcontrolsview.js";
+import { AIHeaderView } from "../../aicore/ui/aiheaderview.js";
+import { AIDisclaimerView } from "../../aicore/ui/aidisclaimerview.js";
+import { type AIContextProvider, type AIContextResourceState } from "../../aichat/model/aichatcontext.js";
 /**
- * The main view of the AI chat plugin.
- *
- * It contains the header, feed and controls views.
- */
+* Returns the root element of the AI chat the given element is in, or `null` when it is in none.
+*
+* Walks up from an element the caller already holds rather than querying the document, which finds nothing when
+* the chat lives in a shadow root. Views inside the chat use it to resolve the container their floating UI must
+* stay within – the `limiter` of a balloon panel.
+*/
+export declare function getAIChatContainer(element: HTMLElement | null | undefined): HTMLElement | null;
+/**
+* The main view of the AI chat plugin.
+*
+* It contains the header, feed and controls views.
+*/
 export declare class AIChatView extends View {
-    chatHeader: AIHeaderView;
-    chatFeed: AIChatFeedView;
-    chatControls: AIChatControlsView;
-    chatDisclaimer: AIDisclaimerView;
-    constructor(locale: Locale, options: {
-        showResizeButton: boolean;
-        contextResourcesSearchInputVisibleFrom?: number;
-    });
-    /**
-     * 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;
-    /**
-     * @inheritDoc
-     */
-    destroy(): void;
+	chatHeader: AIHeaderView;
+	chatFeed: AIChatFeedView;
+	chatControls: AIChatControlsView;
+	chatDisclaimer: AIDisclaimerView;
+	constructor(locale: Locale, options: {
+		bodyCollection: BodyCollection;
+		showResizeButton: boolean;
+		contextResourcesSearchInputVisibleFrom?: number;
+		filesEnabled: boolean;
+	});
+	/**
+	* 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;
 }

package/dist/aichat/ui/controls/aichatchipsoverflowmanager.d.ts

@@ -1,71 +1,81 @@
 /**
- * @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/ui/controls/aichatchipsoverflowmanager
- */
-import { View, type BodyCollection, ButtonView } from '@ckeditor/ckeditor5-ui';
-import { type Locale, Collection } from '@ckeditor/ckeditor5-utils';
-import { type AIChatContextItemButtonView } from './aichatcontextitembuttonview.js';
+* @module ai/aichat/ui/controls/aichatchipsoverflowmanager
+*/
+import { View, type BodyCollection, ButtonView } from "@ckeditor/ckeditor5-ui";
+import { type Locale, Collection } from "@ckeditor/ckeditor5-utils";
+import { type AIChatContextItemButtonView } from "./aichatcontextitembuttonview.js";
 /**
- * Configuration interface for the chips overflow manager.
- */
+* Configuration interface for the chips overflow manager.
+*/
 export interface ChipsOverflowConfig {
-    cssClasses: {
-        showMoreButton: string;
-        showMoreBalloon: string;
-        overflowContainer: string;
-        controlsButton?: string;
-        calculationContainer?: string;
-    };
-    maxVisibleRows?: number;
-    /**
-     * Tolerance for row detection in pixels.
-     */
-    rowDetectionTolerance?: number;
-    showMoreLabelPrefix?: string;
-    viewportOffset?: {
-        top: number;
-        bottom: number;
-    };
+	cssClasses: {
+		showMoreButton: string;
+		showMoreBalloon: string;
+		overflowContainer: string;
+		controlsButton?: string;
+		calculationContainer?: string;
+	};
+	maxVisibleRows?: number;
+	/**
+	* Tolerance for row detection in pixels.
+	*/
+	rowDetectionTolerance?: number;
+	showMoreLabelPrefix?: string;
+	viewportOffset?: {
+		top: number;
+		bottom: number;
+	};
+	/**
+	* Resolves the element the show more balloon must stay within, usually the container the chips are in.
+	*
+	* **Tip**: Resolve it by walking up from an element the consumer already holds (`Element#closest()`) rather than by
+	* querying the document: a `document.querySelector()` call finds nothing when the chips live in a shadow root,
+	* and the balloon silently stops being constrained to anything.
+	*
+	* The balloon is positioned without a limiter when this is not set or resolves to `null`.
+	*/
+	getLimiterElement?: () => HTMLElement | null;
 }
 /**
- * A reusable component for managing chips overflow with show more functionality.
- */
+* A reusable component for managing chips overflow with show more functionality.
+*/
 export declare class AIChatChipsOverflowManager {
-    constructor(locale: Locale, visibleChips: Collection<AIChatContextItemButtonView>, config: ChipsOverflowConfig, bodyCollection: BodyCollection, parentView: View);
-    /**
-     * Sets the container element that holds the chips.
-     */
-    setContainerElement(element: HTMLElement): void;
-    /**
-     * Gets the show more button view.
-     */
-    get showMoreButtonView(): ButtonView | null;
-    /**
-     * Gets the overflow chips collection.
-     */
-    get overflowChips(): Collection<AIChatContextItemButtonView>;
-    /**
-     * Reorganizes chips to handle overflow.
-     */
-    reorganizeChips(): void;
-    /**
-     * Shows the show more balloon panel.
-     */
-    showBalloonPanel(): void;
-    /**
-     * Hides the show more balloon panel.
-     */
-    hideBalloonPanel(): void;
-    /**
-     * Clears all overflow chips and resets the overflow state.
-     * This properly updates the show more button counter and hides it when no overflow items remain.
-     */
-    clear(): void;
-    /**
-     * Destroys the overflow manager and cleans up resources.
-     */
-    destroy(): void;
+	constructor(locale: Locale, visibleChips: Collection<AIChatContextItemButtonView>, config: ChipsOverflowConfig, bodyCollection: BodyCollection, parentView: View);
+	/**
+	* Sets the container element that holds the chips.
+	*/
+	setContainerElement(element: HTMLElement): void;
+	/**
+	* Gets the show more button view.
+	*/
+	get showMoreButtonView(): ButtonView | null;
+	/**
+	* Gets the overflow chips collection.
+	*/
+	get overflowChips(): Collection<AIChatContextItemButtonView>;
+	/**
+	* Reorganizes chips to handle overflow.
+	*/
+	reorganizeChips(): void;
+	/**
+	* Shows the show more balloon panel.
+	*/
+	showBalloonPanel(): void;
+	/**
+	* Hides the show more balloon panel.
+	*/
+	hideBalloonPanel(): void;
+	/**
+	* Clears all overflow chips and resets the overflow state.
+	* This properly updates the show more button counter and hides it when no overflow items remain.
+	*/
+	clear(): void;
+	/**
+	* Destroys the overflow manager and cleans up resources.
+	*/
+	destroy(): void;
 }

package/dist/aichat/ui/controls/aichatcontextitembuttonview.d.ts

@@ -1,46 +1,46 @@
 /**
- * @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/ui/controls/aichatcontextitembuttonview
- */
-import { ButtonView } from '@ckeditor/ckeditor5-ui';
-import { type Locale } from '@ckeditor/ckeditor5-utils';
-import { type AIContextItem } from '../../../aicore/model/aicontext.js';
+* @module ai/aichat/ui/controls/aichatcontextitembuttonview
+*/
+import { ButtonView } from "@ckeditor/ckeditor5-ui";
+import { type Locale } from "@ckeditor/ckeditor5-utils";
+import { type AIContextItem } from "../../../aicore/model/aicontext.js";
 /**
- * A button view representing a context item in the AI chat interface.
- *
- * This component displays a context item (file, document, or URL) as a chip
- * with an icon, label, and optional remove button depending on the readonly state.
- */
+* A button view representing a context item in the AI chat interface.
+*
+* This component displays a context item (file, document, or URL) as a chip
+* with an icon, label, and optional remove button depending on the readonly state.
+*/
 export declare class AIChatContextItemButtonView extends ButtonView {
-    id: string;
-    itemType: AIContextItem['type'];
-    label: string;
-    readonly: boolean;
-    /**
-     * Observable flag indicating if the context item is loading.
-     * @observable
-     */
-    isLoading: boolean;
-    /**
-     * Creates an instance of the context item button view.
-     *
-     * @param locale The locale instance.
-     * @param contextItem The context item to display.
-     * @param readonly Whether the view is in readonly mode.
-     * @param isAnimationOnEnterEnabled Whether the enter animation is enabled.
-     * @param isLoading Whether the context item is loading.
-     */
-    constructor(locale: Locale, contextItem: AIContextItem, readonly: boolean, isAnimationOnEnterEnabled: boolean, isLoading?: boolean);
-    /**
-     * @inheritDoc
-     */
-    render(): void;
-    /**
-     * Disables the enter animation for this chip.
-     * This is useful when moving chips to overflow areas where animation is not desired.
-     */
-    disableAnimationOnEnter(): void;
+	id: string;
+	itemType: AIContextItem["type"];
+	label: string;
+	readonly: boolean;
+	/**
+	* Observable flag indicating if the context item is loading.
+	* @observable
+	*/
+	isLoading: boolean;
+	/**
+	* Creates an instance of the context item button view.
+	*
+	* @param locale The locale instance.
+	* @param contextItem The context item to display.
+	* @param readonly Whether the view is in readonly mode.
+	* @param isAnimationOnEnterEnabled Whether the enter animation is enabled.
+	* @param isLoading Whether the context item is loading.
+	*/
+	constructor(locale: Locale, contextItem: AIContextItem, readonly: boolean, isAnimationOnEnterEnabled: boolean, isLoading?: boolean);
+	/**
+	* @inheritDoc
+	*/
+	override render(): void;
+	/**
+	* Disables the enter animation for this chip.
+	* This is useful when moving chips to overflow areas where animation is not desired.
+	*/
+	disableAnimationOnEnter(): void;
 }