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

package/dist/aiquickactions/aiquickactions.d.ts

@@ -1,270 +1,321 @@
 /**
- * @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/aiquickactions/aiquickactions
- * @publicApi
- */
-import { type Editor, Plugin } from '@ckeditor/ckeditor5-core';
-import { AIQuickActionsUI } from './aiquickactionsui.js';
-import { AIQuickActionsEditing } from './aiquickactionsediting.js';
-import { AIActions } from '../aiactions/aiactions.js';
+* @module ai/aiquickactions/aiquickactions
+* @publicApi
+*/
+import { type Editor, Plugin, type PluginDependenciesOf } from "@ckeditor/ckeditor5-core";
+import { AIQuickActionsUI } from "./aiquickactionsui.js";
+import { AIQuickActionsEditing } from "./aiquickactionsediting.js";
+import { AIActions } from "../aiactions/aiactions.js";
+import { type AIContextRef } from "../aicore/model/aicontextref.js";
 /**
- * The AI Quick Actions feature.
- *
- * Quick Actions streamline routine content transformations by offering one-click AI-powered suggestions directly within the editor.
- * You can also ask questions about your selected text in the Chat to get instant AI insights and analysis.
- *
- * You can configure the feature by setting the {@link module:ai/aiquickactions/aiquickactions~AIQuickActionsConfig} property.
- *
- * Learn more about AI features in CKEditor in the {@glink features/ai/ckeditor-ai-overview AI Overview} documentation.
- */
+* The AI Quick Actions feature.
+*
+* Quick Actions streamline routine content transformations by offering one-click AI-powered suggestions directly within the editor.
+* You can also ask questions about your selected text in the Chat to get instant AI insights and analysis.
+*
+* You can configure the feature by setting the {@link module:ai/aiquickactions/aiquickactions~AIQuickActionsConfig} property.
+*
+* Learn more about AI features in CKEditor in the {@glink features/ai/ckeditor-ai-overview AI Overview} documentation.
+*/
 export declare class AIQuickActions extends Plugin {
-    /**
-     * @inheritDoc
-     */
-    static get requires(): readonly [typeof AIQuickActionsUI, typeof AIQuickActionsEditing, typeof AIActions];
-    /**
-     * @inheritDoc
-     */
-    static get pluginName(): "AIQuickActions";
-    /**
-     * @inheritDoc
-     */
-    static get isOfficialPlugin(): true;
-    /**
-     * @inheritDoc
-     */
-    static get isPremiumPlugin(): true;
-    constructor(editor: Editor);
+	/**
+	* @inheritDoc
+	*/
+	static get requires(): PluginDependenciesOf<[AIQuickActionsUI, AIQuickActionsEditing, AIActions]>;
+	/**
+	* @inheritDoc
+	*/
+	static get pluginName(): "AIQuickActions";
+	/**
+	* @inheritDoc
+	*/
+	static override get isOfficialPlugin(): true;
+	/**
+	* @inheritDoc
+	*/
+	static override get isPremiumPlugin(): true;
+	constructor(editor: Editor);
 }
 /**
- * The configuration of the {@link module:ai/aiquickactions/aiquickactions~AIQuickActions AI Quick Actions feature}.
- *
- * The properties defined in this config are set in the `config.ai.quickActions` namespace.
- *
- * ```ts
- * ClassicEditor
- * 	.create( {
- * 		ai: {
- * 			quickActions: {
- * 				// AI Quick Actions configuration.
- * 			}
- * 		}
- * 	} )
- * 	.then( ... )
- * 	.catch( ... );
- * ```
- *
- * See {@link module:ai/aiconfig~AIConfig the full AI configuration}.
- *
- * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
- */
+* The configuration of the {@link module:ai/aiquickactions/aiquickactions~AIQuickActions AI Quick Actions feature}.
+*
+* The properties defined in this config are set in the `config.ai.quickActions` namespace.
+*
+* ```ts
+* ClassicEditor
+* 	.create( {
+* 		ai: {
+* 			quickActions: {
+* 				// AI Quick Actions configuration.
+* 			}
+* 		}
+* 	} )
+* 	.then( ... )
+* 	.catch( ... );
+* ```
+*
+* See {@link module:ai/aiconfig~AIConfig the full AI configuration}.
+*
+* See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
+*/
 export interface AIQuickActionsConfig {
-    /**
-     * The extra commands to add to the AI Quick Actions feature to become available for the user. You can fine-tune
-     * the commands by specifying the type, prompt, and other properties. By default, the extra commands land in the
-     * "Other" group in the user interface.
-     *
-     * The following example will add 3 new commands to the AI Quick Actions feature:
-     *
-     * ```ts
-     * ClassicEditor
-     * 	.create( {
-     * 		// ... Other configuration options ...
-     * 		ai: {
-     * 			quickActions: {
-     * 				extraCommands: [
-     * 					{
-     *						id: 'add-quote-from-famous-person',
-     *						label: 'Add a quote from a famous person',
-     *						prompt: 'Add a quote from a known person, which would make sense in the context of the selected text.',
-     *						type: 'action',
-     *						model: 'claude-4-sonnet'
-     *					},
-     *					{
-     *						id: 'summarize-in-bullet-points',
-     *						label: 'Summarize',
-     *						displayedPrompt: 'Summarize in 5 bullet points',
-     *						prompt: 'Summarize the selected text in 5 bullet points.',
-     *						type: 'chat'
-     *					},
-     *					{
-     *						id: 'include-more-sarcasm',
-     *						label: 'Add sarcasm',
-     *						prompt: 'Rewrite using a sarcastic tone.',
-     *						type: 'action',
-     *						model: 'claude-4-sonnet'
-     *					}
-     * 				],
-     * 			},
-     * 		}
-     * 	} )
-     * 	.then( ... )
-     * 	.catch( ... );
-     * ```
-     */
-    extraCommands?: Array<AIQuickActionCustomDefinition>;
-    /**
-     * The ids of the commands to remove from the AI Quick Actions feature. Removing all commands from a specific category
-     * will remove the category from the user interface.
-     *
-     * The defaults are as follows:
-     *
-     * - `'ask-ai`,
-     * - "Chat commands" category
-     * 	- `'explain'`,
-     * 	- `'summarize'`,
-     * 	- `'highlight-key-points'`,
-     * - `'improve-writing'`,
-     * - `'continue'`,
-     * - `'fix-grammar'`,
-     * - "Adjust length" category
-     * 	- `'make-shorter'`,
-     * 	- `'make-longer'`,
-     * - "Change tone" category
-     * 	- `'make-tone-casual'`,
-     * 	- `'make-tone-direct'`,
-     * 	- `'make-tone-friendly'`,
-     * 	- `'make-tone-confident'`,
-     * 	- `'make-tone-professional'`,
-     * - "Translate" category
-     * 	- `'translate-to-english'`,
-     * 	- `'translate-to-chinese'`,
-     * 	- `'translate-to-french'`,
-     * 	- `'translate-to-german'`,
-     * 	- `'translate-to-italian'`,
-     * 	- `'translate-to-portuguese'`,
-     * 	- `'translate-to-russian'`
-     *
-     * The following example will remove the "Explain" and "Summarize" commands from the user interface:
-     *
-     * ```ts
-     * ClassicEditor
-     * 	.create( {
-     * 		// ... Other configuration options ...
-     * 		ai: {
-     * 			quickActions: {
-     *				removeCommands: [
-     *					'explain',
-     *					'summarize',
-     *					// ...
-     *				]
-     *			},
-     * 		}
-     * 	} )
-     * 	.then( ... )
-     * 	.catch( ... );
-     * ```
-     */
-    removeCommands?: Array<string>;
-    /**
-     * Whether to enable search functionality in the AI Quick Actions dropdown.
-     *
-     * When enabled, users can search through available quick actions using a search input field.
-     * When disabled, the search input is hidden and all actions are displayed in a list.
-     *
-     * @default true
-     *
-     * ```ts
-     * ClassicEditor
-     * 	.create( {
-     * 		// ... Other configuration options ...
-     * 		ai: {
-     * 			quickActions: {
-     * 				isSearchEnabled: false
-     * 			}
-     * 		}
-     * 	} )
-     * 	.then( ... )
-     * 	.catch( ... );
-     * ```
-     */
-    isSearchEnabled?: boolean;
+	/**
+	* The extra commands to add to the AI Quick Actions feature to become available for the user. You can fine-tune
+	* the commands by specifying the type, prompt, and other properties. By default, the extra commands land in the
+	* "Other" group in the user interface.
+	*
+	* The following example will add 3 new commands to the AI Quick Actions feature:
+	*
+	* ```ts
+	* ClassicEditor
+	* 	.create( {
+	* 		// ... Other configuration options ...
+	* 		ai: {
+	* 			quickActions: {
+	* 				extraCommands: [
+	* 					{
+	*						id: 'add-quote-from-famous-person',
+	*						label: 'Add a quote from a famous person',
+	*						prompt: 'Add a quote from a known person, which would make sense in the context of the selected text.',
+	*						type: 'action'
+	*						// No `model` specified — uses the default configured in `ai.models.defaultModelId`.
+	*					},
+	*					{
+	*						id: 'summarize-in-bullet-points',
+	*						label: 'Summarize',
+	*						displayedPrompt: 'Summarize in 5 bullet points',
+	*						prompt: 'Summarize the selected text in 5 bullet points.',
+	*						type: 'chat'
+	*					},
+	*					{
+	*						id: 'include-more-sarcasm',
+	*						label: 'Add sarcasm',
+	*						prompt: 'Rewrite using a sarcastic tone.',
+	*						type: 'action',
+	*						model: 'claude-4-6-sonnet' // Pin a specific model for this action.
+	*					}
+	* 				],
+	* 			},
+	* 		}
+	* 	} )
+	* 	.then( ... )
+	* 	.catch( ... );
+	* ```
+	*/
+	extraCommands?: Array<AIQuickActionCustomDefinition>;
+	/**
+	* The IDs of the commands to remove from the AI Quick Actions feature. Removing all commands from a specific category
+	* will remove the category from the user interface.
+	*
+	* The defaults are as follows:
+	*
+	* - `'ask-ai`,
+	* - "Chat commands" category
+	* 	- `'explain'`,
+	* 	- `'summarize'`,
+	* 	- `'highlight-key-points'`,
+	* - `'improve-writing'`,
+	* - `'continue'`,
+	* - `'fix-grammar'`,
+	* - "Adjust length" category
+	* 	- `'make-shorter'`,
+	* 	- `'make-longer'`,
+	* - "Change tone" category
+	* 	- `'make-tone-casual'`,
+	* 	- `'make-tone-direct'`,
+	* 	- `'make-tone-friendly'`,
+	* 	- `'make-tone-confident'`,
+	* 	- `'make-tone-professional'`,
+	* - "Translate" category
+	* 	- `'translate-to-english'`,
+	* 	- `'translate-to-chinese'`,
+	* 	- `'translate-to-french'`,
+	* 	- `'translate-to-german'`,
+	* 	- `'translate-to-italian'`,
+	* 	- `'translate-to-portuguese'`,
+	* 	- `'translate-to-russian'`
+	*
+	* The following example will remove the "Explain" and "Summarize" commands from the user interface:
+	*
+	* ```ts
+	* ClassicEditor
+	* 	.create( {
+	* 		// ... Other configuration options ...
+	* 		ai: {
+	* 			quickActions: {
+	*				removeCommands: [
+	*					'explain',
+	*					'summarize',
+	*					// ...
+	*				]
+	*			},
+	* 		}
+	* 	} )
+	* 	.then( ... )
+	* 	.catch( ... );
+	* ```
+	*/
+	removeCommands?: Array<string>;
+	/**
+	* Whether to enable search functionality in the AI Quick Actions dropdown.
+	*
+	* When enabled, users can search through available quick actions using a search input field.
+	* When disabled, the search input is hidden and all actions are displayed in a list.
+	*
+	* @default true
+	*
+	* ```ts
+	* ClassicEditor
+	* 	.create( {
+	* 		// ... Other configuration options ...
+	* 		ai: {
+	* 			quickActions: {
+	* 				isSearchEnabled: false
+	* 			}
+	* 		}
+	* 	} )
+	* 	.then( ... )
+	* 	.catch( ... );
+	* ```
+	*/
+	isSearchEnabled?: boolean;
 }
 /**
- * Represents all quick action definition types:
- *
- * * {@link module:ai/aiquickactions/aiquickactions~AIQuickActionCustomActionDefinition Quick action},
- * * {@link module:ai/aiquickactions/aiquickactions~AIQuickActionCustomChatDefinition Chat action}.
- */
+* Represents all quick action definition types:
+*
+* * {@link module:ai/aiquickactions/aiquickactions~AIQuickActionCustomActionDefinition Quick action},
+* * {@link module:ai/aiquickactions/aiquickactions~AIQuickActionCustomChatDefinition Chat action}.
+*/
 export type AIQuickActionCustomDefinition = AIQuickActionCustomActionDefinition | AIQuickActionCustomChatDefinition;
 /**
- * Defines the different types of AI quick actions available in the editor.
- * Each type determines how the action will be presented and executed.
- *
- * Available types:
- * * `'action'`: display results in a balloon popup for quick inline operations,
- * * `'chat'`: opens the AI Chat interface for interactive conversations.
- */
-export type AIQuickActionType = 'chat' | 'action';
+* Defines the different types of AI quick actions available in the editor.
+* Each type determines how the action will be presented and executed.
+*
+* Available types:
+* * `'action'`: display results in a balloon popup for quick inline operations,
+* * `'chat'`: opens the AI Chat interface for interactive conversations.
+*/
+export type AIQuickActionType = "chat" | "action";
 /**
- * The base definition for all action types.
- */
+* The base definition for all action types.
+*/
 export interface AIQuickActionCustomBaseDefinition {
-    /**
-     * The unique identifier of the action.
-     */
-    readonly id: string;
-    /**
-     * The human-readable label of the action.
-     */
-    readonly label: string;
-    /**
-     * The type of the action.
-     */
-    readonly type: AIQuickActionType;
-    /**
-     * The prompt to be sent to the AI model when the action is executed.
-     */
-    readonly prompt: string;
-    /**
-     * The AI model to use for the action. For `'action'` type, if not specified, the default model will be used.
-     * For `'chat'` type, if not specified, the model currently selected in the AI Chat will be used.
-     */
-    readonly model?: string;
+	/**
+	* The unique identifier of the action.
+	*/
+	readonly id: string;
+	/**
+	* The human-readable label of the action.
+	*/
+	readonly label: string;
+	/**
+	* The type of the action.
+	*/
+	readonly type: AIQuickActionType;
+	/**
+	* The AI model to use for the action. For `'action'` type, if not specified, the default model will be used.
+	* For `'chat'` type, if not specified, the model currently selected in the AI Chat will be used.
+	*/
+	readonly model?: string;
 }
 /**
- * A custom AI quick action definition.
- *
- * An example of an action that inserts content in the editor. The `model` property is optional — if not specified,
- * the default model (from `ai.models.defaultModelId` configuration or the first available model) will be used:
- *
- * ```ts
- * {
- *	id: 'add-quote-from-famous-person',
- *	label: 'Add a quote from a famous person',
- *	prompt: 'Add a quote from a known person, which would make sense in the context of the selected text.',
- *	type: 'action',
- *	model: 'claude-4-sonnet'
- * }
- * ```
- */
-export interface AIQuickActionCustomActionDefinition extends AIQuickActionCustomBaseDefinition {
-    type: 'action';
-}
+* A custom AI quick action definition.
+*
+* The action needs a prompt source, provided in one of three ways:
+*
+* * an inline `prompt` string - sent as the prompt,
+* * a `context` reference - the referenced context drives the action (for example through a prompt it contains),
+* * both - the inline `prompt` is used and the `context` is attached as additional reference material (for example a file).
+*
+* The `model` property is optional. If not specified, the default model (from the `ai.models.defaultModelId`
+* configuration or the first available model) is used.
+*
+* ```ts
+* {
+*	id: 'add-quote-from-famous-person',
+*	label: 'Add a quote from a famous person',
+*	prompt: 'Add a quote from a known person, which would make sense in the context of the selected text.',
+*	type: 'action',
+*	model: 'claude-4-6-sonnet'
+* }
+* ```
+*
+* The same action using a `context` reference instead of an inline `prompt`:
+*
+* ```ts
+* {
+*	id: 'add-quote-from-famous-person',
+*	label: 'Add a quote from a famous person',
+*	context: { id: 'my-context', promptId: 'add-quote' },
+*	type: 'action',
+*	model: 'claude-4-6-sonnet'
+* }
+* ```
+*
+* An inline `prompt` combined with a `context` that attaches a single file as reference material:
+*
+* ```ts
+* {
+*	id: 'add-quote-from-famous-person',
+*	label: 'Add a quote from a famous person',
+*	prompt: 'Add a quote from a known person, which would make sense in the context of the selected text.',
+*	context: { id: 'my-context', fileId: 'famous-quotes' },
+*	type: 'action',
+*	model: 'claude-4-6-sonnet'
+* }
+* ```
+*/
+export type AIQuickActionCustomActionDefinition = AIQuickActionCustomBaseDefinition & {
+	type: "action";
+	/**
+	* The prompt to be sent to the AI model when the action is executed.
+	*
+	* At least one prompt source is required: an inline `prompt`, a `context` that carries a prompt (a whole context
+	* or a `promptId` reference), or both. A `context` that references only a single file (`fileId`) cannot drive the
+	* action on its own and must be combined with an inline `prompt`.
+	*/
+	readonly prompt?: string;
+	/**
+	* A context reference attached to the action.
+	*
+	* When no inline `prompt` is provided, the referenced context drives the action (a whole context or a `promptId`
+	* reference). When combined with an inline `prompt`, it is attached as additional reference material (for example
+	* a single file).
+	*
+	* @experimental **Experimental:** This is a production-ready API but may change in minor releases
+	* without the standard deprecation policy. Check the changelog for migration guidance.
+	*/
+	readonly context?: AIContextRef;
+};
 /**
- * A custom AI quick action definition that interacts with {@link module:ai/aichat/aichat~AIChat AI Chat}.
- *
- * It will open the {@link module:ai/aichat/aichat~AIChat AI Chat} interface for interactive conversations.
- * If `model` is specified, it will be selected for the new chat conversation. Otherwise, the model currently
- * selected in the AI Chat will be used:
- *
- * ```ts
- * {
- *	id: 'summarize-in-bullet-points',
- *	label: 'Summarize',
- *	displayedPrompt: 'Summarize in 5 bullet points',
- *	prompt: 'Summarize the selected text in 5 bullet points.',
- *	type: 'chat'
- * }
- * ```
- */
+* A custom AI quick action definition that interacts with {@link module:ai/aichat/aichat~AIChat AI Chat}.
+*
+* It will open the {@link module:ai/aichat/aichat~AIChat AI Chat} interface for interactive conversations.
+* If `model` is specified, it will be selected for the new chat conversation. Otherwise, the model currently
+* selected in the AI Chat will be used:
+*
+* ```ts
+* {
+*	id: 'summarize-in-bullet-points',
+*	label: 'Summarize',
+*	displayedPrompt: 'Summarize in 5 bullet points',
+*	prompt: 'Summarize the selected text in 5 bullet points.',
+*	type: 'chat'
+* }
+* ```
+*/
 export interface AIQuickActionCustomChatDefinition extends AIQuickActionCustomBaseDefinition {
-    type: 'chat';
-    /**
-     * The prompt shown in the AI Chat UI when the action is executed. If not specified, the `prompt` property value will be used.
-     */
-    displayedPrompt: string;
+	type: "chat";
+	/**
+	* The prompt to be sent to the AI Chat when the action is executed.
+	*/
+	readonly prompt: string;
+	/**
+	* The prompt shown in the AI Chat UI when the action is executed. If not specified, the `prompt` property value will be used.
+	*/
+	displayedPrompt: string;
 }

package/dist/aiquickactions/aiquickactionscommand.d.ts

@@ -1,15 +1,15 @@
 /**
- * @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/aiquickactions/aiquickactionscommand
- */
-import { Command } from '@ckeditor/ckeditor5-core';
-import { type AIQuickActionDefinition } from './aiquickactionsui.js';
+* @module ai/aiquickactions/aiquickactionscommand
+*/
+import { Command } from "@ckeditor/ckeditor5-core";
+import { type AIQuickActionDefinition } from "./aiquickactionsui.js";
 /**
- * AI Quick Actions command for executing various AI-powered actions.
- */
+* AI Quick Actions command for executing various AI-powered actions.
+*/
 export declare class AIQuickActionsCommand extends Command {
-    execute(action: AIQuickActionDefinition): void;
+	override execute(action: AIQuickActionDefinition): void;
 }

package/dist/aiquickactions/aiquickactionsediting.d.ts

@@ -1,26 +1,26 @@
 /**
- * @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/aiquickactions/aiquickactionsediting
- */
-import { Plugin } from '@ckeditor/ckeditor5-core';
+* @module ai/aiquickactions/aiquickactionsediting
+*/
+import { Plugin } from "@ckeditor/ckeditor5-core";
 export declare class AIQuickActionsEditing extends Plugin {
-    /**
-     * @inheritDoc
-     */
-    static get pluginName(): "AIQuickActionsEditing";
-    /**
-     * @inheritDoc
-     */
-    static get isOfficialPlugin(): true;
-    /**
-     * @inheritDoc
-     */
-    static get isPremiumPlugin(): true;
-    /**
-     * @inheritDoc
-     */
-    init(): void;
+	/**
+	* @inheritDoc
+	*/
+	static get pluginName(): "AIQuickActionsEditing";
+	/**
+	* @inheritDoc
+	*/
+	static override get isOfficialPlugin(): true;
+	/**
+	* @inheritDoc
+	*/
+	static override get isPremiumPlugin(): true;
+	/**
+	* @inheritDoc
+	*/
+	init(): void;
 }