@ckeditor/ckeditor5-ai

/** * @license Copyright (c) 2003-2025, CKSource Holding sp. z o.o. All rights reserved. * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options */ /** * @module ai/aiconfig * @publicApi */ import { type AIAssistantConfig } from './aiassistant/aiassistant.js'; import { type AIChatConfig } from './aichat/aichat.js'; import { type AISuggestionActionName } from './aichat/ui/feed/aichatfeedsuggestionitemactionsview.js'; import { type AIQuickActionsConfig } from './aiquickactions/aiquickactions.js'; import { type AIReviewModeConfig } from './aireviewmode/aireviewmode.js'; /** * The configuration for all AI-related functionalities. * * Provides configuration properties for both AI features and AI adapters (which connect to the external AI services), * * ```ts * ClassicEditor * .create( editorElement, { * ai: { * ... * } * } ) * .then( ... ) * .catch( ... ); * ``` * * See {@link module:core/editor/editorconfig~EditorConfig all editor configuration options}. */ export interface AIConfig { /** * The URL of the AI service endpoint. * * This endpoint is used by AI features: AI Chat, AI Quick Actions, and AI Review Mode. * It does not affect the AI Assistant feature, which uses its own adapter configuration. * * **NOTE:** By default, the plugin uses the default AI service endpoint delivered by CKEditor Cloud Services. * * @default 'https://ai.cke-cs.com/v1' */ serviceUrl?: string; /** * The configuration of the {@link module:ai/aiassistant/aiassistant~AIAssistant AI Assistant feature}. * * Read more in {@link module:ai/aiassistant/aiassistant~AIAssistantConfig}. */ assistant?: AIAssistantConfig; /** * The configuration of the AI user interface provided by the {@link module:ai/aitabs/aitabs~AITabs} plugin. */ container?: AIContainerConfig; /** * The configuration of the {@link module:ai/aichat/aichat~AIChat AI Chat feature}. * * Read more in {@link module:ai/aichat/aichat~AIChatConfig}. */ chat?: AIChatConfig; /** * The configuration of the AI Quick Actions feature. * * Read more in {@link module:ai/aiquickactions/aiquickactions~AIQuickActionsConfig}. */ quickActions?: AIQuickActionsConfig; /** * The configuration of the {@link module:ai/aireviewmode/aireviewmode~AIReviewMode AI Review Mode feature}. */ reviewMode?: AIReviewModeConfig; /** * Defines what actions are available for the user when interacting with AI responses in AI Chat and AI Quick Actions features. * * Users can perform following three actions: * * * `'applySuggestion'` - applies the presented change directly into the editor content. * * `'insertSuggestion'` - applies the presented change as a suggestion, which can be later on accepted or rejected. * * `'showChangeInText'` - locates the changed part of document in the editor and opens a balloon with the preview. * * By default, the editor configuration enables all available actions, in following order: * * ```ts * [ 'applySuggestion', 'insertSuggestion', 'showChangeInText' ] * ``` * * This setting impacts: * * * The action dropdown located below an AI reply in the chat feed. The setting affects the main action for the button, as well as * actions available in the dropdown and their order. * * The buttons located in the header of each change preview in the chat feed. Note, that the header is visible only if the AI Chat * proposed multiple changes. * * The buttons located in the balloon which shows the change preview. * * Through this configuration option, you can change how users use the AI replies. For example, if you want to force users to always * insert AI-proposed changes as suggestions, omit `'applySuggestion'` action. * * Please note other factors that impact the availability of these actions: * * * Buttons related to `'applySuggestion'` action are hidden if {@link module:track-changes/trackchanges~TrackChanges track changes} * feature is turned on. * * Buttons related to `'insertSuggestion'` action are hidden if {@link module:track-changes/trackchanges~TrackChanges track changes} * feature is not loaded in the editor. * * Please note, that due to these factors, it is possible to accidentally configure the editor in a way, that no UI elements are * presented to the user. */ availableReplyActions?: Array<AISuggestionActionName>; } export type AIContainerType = 'sidebar' | 'overlay' | 'custom'; export type AIContainerSide = 'left' | 'right'; export interface AIContainerBase { type: AIContainerType; /** * This option is used to show or hide the resize button in the AI user interface. * * Defaults to `true`. */ showResizeButton?: boolean; /** * Whether the AI interface should be visible when the editor is created. */ visibleByDefault?: boolean; } /** * The configuration of the AI user interface container in the sidebar mode. Provide an existing DOM * element to use as the container the AI user interface will automatically render into that element. * * Additionally, the {@link module:ai/aitabs/aitabs~AITabs tab buttons} can be positioned on the preferred * side of the container. * * ```ts * ClassicEditor * .create( document.querySelector( '#editor' ), { * // ... Other configuration options ... * ai: { * container: { * type: 'sidebar', * * // Existing DOM element to use as the container for the AI user interface. * element: document.querySelector( '#ai-sidebar-container' ), * * // (Optional) The preferred side of the element to position the tab buttons. * side: 'right' * }, * } * } ) * .then( ... ) * .catch( ... ); * ``` */ export interface AIContainerSidebar extends AIContainerBase { type: 'sidebar'; element: HTMLElement; side?: AIContainerSide; } /** * The configuration of the AI user interface container in the overlay mode. In this mode, the AI user * interface is displayed on top of the web page on a preferred side. This mode is best suited * for integrations with limited space. * * ```ts * ClassicEditor * .create( document.querySelector( '#editor' ), { * // ... Other configuration options ... * ai: { * container: { * type: 'overlay', * side: 'right' * }, * } * } ) * .then( ... ) * .catch( ... ); * ``` */ export interface AIContainerOverlay extends AIContainerBase { type: 'overlay'; side?: AIContainerSide; } /** * The configuration of the AI user interface container in the custom mode. * * In this mode, integrator is responsible for rendering the AI user interface in the web page. * * * Use {@link module:ai/aitabs/aitabs~AITabs#view} to access the view of the AI user interface, * * Use {@link module:ai/aitabs/tabs/aitabsview~AITabsView#getTabIds} to read available IDs of individual tabs in the AI user interface, * * Use {@link module:ai/aitabs/tabs/aitabsview~AITabsView#getTab} to access individual tab views in the AI user interface, * * Use {@link module:ai/aitabs/tabs/aitabsview~AITabsView#addTab} to add a new tab to the AI user interface, * * Use {@link module:ai/aitabs/tabs/aitabsview~AITabsView#activateTab} to switch between tabs from the code. * * For example, to integrate the AI user interface with custom containers on the web page, use the following code: * * ```ts * const tabsPlugin = editor.plugins.get( 'AITabs' ); * * for ( const id of tabsPlugin.view.getTabIds() ) { * const tab = tabsPlugin.view.getTab( id ); * * // Display tab button and panel in a custom container. * myButtonsContainer.appendChild( tab.button.element ); * myPanelContainer.appendChild( tab.panel.element ); * } * ``` */ export interface AIContainerCustom extends AIContainerBase { type: 'custom'; } /** * The configuration of the AI user interface provided by the {@link module:ai/aitabs/aitabs~AITabs} plugin. * * The AI user interface can operate in three different modes: * * * {@link module:ai/aiconfig~AIContainerSidebar} - the AI user interface is displayed in a specific DOM element, * * {@link module:ai/aiconfig~AIContainerOverlay} - the AI user interface is displayed on top of the web page, * * {@link module:ai/aiconfig~AIContainerCustom} - the AI user interface is displayed in a custom way. */ export type AIContainerConfig = AIContainerSidebar | AIContainerOverlay | AIContainerCustom;