@ckeditor/ckeditor5-track-changes 48.2.0 → 48.3.0-alpha.0

package/dist/trackchanges.d.ts

@@ -1,189 +1,189 @@
 /**
- * @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 track-changes/trackchanges
- * @publicApi
- */
-import { Plugin } from '@ckeditor/ckeditor5-core';
-import { Comments } from '@ckeditor/ckeditor5-comments';
-import { TrackChangesUI } from './trackchangesui.js';
-import { TrackChangesEditing } from './trackchangesediting.js';
-import '@ckeditor/ckeditor5-collaboration-core';
-import type { Suggestion, SuggestionJSON } from './suggestion.js';
+* @module track-changes/trackchanges
+* @publicApi
+*/
+import { Plugin, type PluginDependenciesOf } from "@ckeditor/ckeditor5-core";
+import { Comments } from "@ckeditor/ckeditor5-comments";
+import { TrackChangesUI } from "./trackchangesui.js";
+import { TrackChangesEditing } from "./trackchangesediting.js";
+import "@ckeditor/ckeditor5-collaboration-core";
+import type { Suggestion, SuggestionJSON } from "./suggestion.js";
 /**
- * A plugin that provides track changes mode for the editor. In track changes mode, all insertions are visually marked and all deletions
- * are not deleted but also visually marked. Unsupported commands are disabled when the editor is in the track changes mode.
- *
- * To learn how to integrate the track changes feature with your editor, refer to the
- * {@glink features/collaboration/track-changes/track-changes-integration Track changes integration} guide.
- *
- * Basic API:
- *
- * ```ts
- * // Get the track changes plugin:
- * const trackChangesPlugin = editor.plugins.get( 'TrackChanges' );
- *
- * // Add a suggestion:
- * trackChangesPlugin.addSuggestion( suggestionData );
- *
- * // Get all suggestions:
- * trackChangesPlugin.getSuggestions();
- *
- * // Set the adapter:
- * trackChangesPlugin.adapter = {
- * 		// ...
- * }
- * ```
- *
- * The plugin registers several commands:
- *
- * * `trackChanges` – Toggles the track changes mode in the editor.
- * * `acceptSuggestion` – Accepts a suggestion with the specified ID.
- * * `discardSuggestion` – Discards a suggestion with the specified ID.
- * * `acceptAllSuggestions` – Accepts all suggestions.
- * * `discardAllSuggestions` – Discards all suggestions.
- * * `acceptSelectedSuggestions` – Accepts all suggestions in the current selection.
- * * `discardSelectedSuggestions` – Discards all suggestions in the current selection.
- *
- * Examples:
- *
- * ```ts
- * editor.execute( 'trackChanges' );
- * editor.execute( 'acceptSuggestion', 'suggestion-1' );
- * editor.execute( 'discardSuggestion', 'suggestion-1' );
- * editor.execute( 'acceptAllSuggestions' );
- * editor.execute( 'discardAllSuggestions' );
- * editor.execute( 'acceptSelectedSuggestions' );
- * editor.execute( 'discardSelectedSuggestions' )
- * ```
- *
- * Note that there is no command to add a suggestion. This is because suggestions
- * are added automatically when editing commands are executed while the editor is in track
- * changes mode. For instance:
- *
- * ```ts
- * // Turn on the track changes mode:
- * editor.execute( 'trackChanges' );
- *
- * // Insert some text. It will be automatically inserted as a suggestion:
- * editor.execute( 'input', { text: 'foo' } );
- * ```
- */
+* A plugin that provides track changes mode for the editor. In track changes mode, all insertions are visually marked and all deletions
+* are not deleted but also visually marked. Unsupported commands are disabled when the editor is in the track changes mode.
+*
+* To learn how to integrate the track changes feature with your editor, refer to the
+* {@glink features/collaboration/track-changes/track-changes-integration Track changes integration} guide.
+*
+* Basic API:
+*
+* ```ts
+* // Get the track changes plugin:
+* const trackChangesPlugin = editor.plugins.get( 'TrackChanges' );
+*
+* // Add a suggestion:
+* trackChangesPlugin.addSuggestion( suggestionData );
+*
+* // Get all suggestions:
+* trackChangesPlugin.getSuggestions();
+*
+* // Set the adapter:
+* trackChangesPlugin.adapter = {
+* 		// ...
+* }
+* ```
+*
+* The plugin registers several commands:
+*
+* * `trackChanges` – Toggles the track changes mode in the editor.
+* * `acceptSuggestion` – Accepts a suggestion with the specified ID.
+* * `discardSuggestion` – Discards a suggestion with the specified ID.
+* * `acceptAllSuggestions` – Accepts all suggestions.
+* * `discardAllSuggestions` – Discards all suggestions.
+* * `acceptSelectedSuggestions` – Accepts all suggestions in the current selection.
+* * `discardSelectedSuggestions` – Discards all suggestions in the current selection.
+*
+* Examples:
+*
+* ```ts
+* editor.execute( 'trackChanges' );
+* editor.execute( 'acceptSuggestion', 'suggestion-1' );
+* editor.execute( 'discardSuggestion', 'suggestion-1' );
+* editor.execute( 'acceptAllSuggestions' );
+* editor.execute( 'discardAllSuggestions' );
+* editor.execute( 'acceptSelectedSuggestions' );
+* editor.execute( 'discardSelectedSuggestions' )
+* ```
+*
+* Note that there is no command to add a suggestion. This is because suggestions
+* are added automatically when editing commands are executed while the editor is in track
+* changes mode. For instance:
+*
+* ```ts
+* // Turn on the track changes mode:
+* editor.execute( 'trackChanges' );
+*
+* // Insert some text. It will be automatically inserted as a suggestion:
+* editor.execute( 'input', { text: 'foo' } );
+* ```
+*/
 export declare class TrackChanges extends Plugin {
-    static get requires(): readonly [typeof TrackChangesEditing, typeof TrackChangesUI, typeof Comments];
-    static get pluginName(): "TrackChanges";
-    /**
-     * @inheritDoc
-     */
-    static get isOfficialPlugin(): true;
-    /**
-     * @inheritDoc
-     */
-    static get isPremiumPlugin(): true;
-    /**
-     * An adapter object that should communicate with the data source to fetch or save the suggestion data.
-     *
-     * This is a shorthand to {@link module:track-changes/trackchangesediting~TrackChangesEditing#adapter `TrackChangesEditing#adapter`}.
-     */
-    set adapter(adapter: TrackChangesAdapter | null);
-    get adapter(): TrackChangesAdapter | null;
-    /**
-     * Adds suggestion data.
-     *
-     * Use this method to load the suggestion data during the editor initialization if you do not use the adapter integration.
-     */
-    addSuggestion(suggestionData: SuggestionData): Suggestion;
-    getSuggestions(options: {
-        skipNotAttached?: boolean;
-        toJSON: true;
-    }): Array<SuggestionJSON>;
-    getSuggestions(options?: {
-        skipNotAttached?: boolean;
-        toJSON?: false;
-    }): Array<Suggestion>;
-    getSuggestions(options: {
-        skipNotAttached?: boolean;
-        toJSON: boolean;
-    }): Array<Suggestion> | Array<SuggestionJSON>;
-    /**
-     * Returns the suggestion instance for a given ID.
-     */
-    getSuggestion(id: string): Suggestion;
+	static get requires(): PluginDependenciesOf<[TrackChangesEditing, TrackChangesUI, Comments]>;
+	static get pluginName(): "TrackChanges";
+	/**
+	* @inheritDoc
+	*/
+	static override get isOfficialPlugin(): true;
+	/**
+	* @inheritDoc
+	*/
+	static override get isPremiumPlugin(): true;
+	/**
+	* An adapter object that should communicate with the data source to fetch or save the suggestion data.
+	*
+	* This is a shorthand to {@link module:track-changes/trackchangesediting~TrackChangesEditing#adapter `TrackChangesEditing#adapter`}.
+	*/
+	set adapter(adapter: TrackChangesAdapter | null);
+	get adapter(): TrackChangesAdapter | null;
+	/**
+	* Adds suggestion data.
+	*
+	* Use this method to load the suggestion data during the editor initialization if you do not use the adapter integration.
+	*/
+	addSuggestion(suggestionData: SuggestionData): Suggestion;
+	getSuggestions(options: {
+		skipNotAttached?: boolean;
+		toJSON: true;
+	}): Array<SuggestionJSON>;
+	getSuggestions(options?: {
+		skipNotAttached?: boolean;
+		toJSON?: false;
+	}): Array<Suggestion>;
+	getSuggestions(options: {
+		skipNotAttached?: boolean;
+		toJSON: boolean;
+	}): Array<Suggestion> | Array<SuggestionJSON>;
+	/**
+	* Returns the suggestion instance for a given ID.
+	*/
+	getSuggestion(id: string): Suggestion;
 }
 /**
- * Track changes adapter.
- *
- * The track changes adapter is an object that communicates asynchronously with the data source to fetch or save the suggestion data.
- * It is used internally by the track changes feature whenever a suggestion is loaded, created or deleted.
- *
- * The adapter is optional. You might need to provide it if you are {@glink features/collaboration/track-changes/track-changes-integration}
- * using the track changes feature without real-time collaboration.
- *
- * To set the adapter, overwrite {@link module:track-changes/trackchanges~TrackChanges#adapter the `TrackChanges#adapter` property}.
- */
+* Track changes adapter.
+*
+* The track changes adapter is an object that communicates asynchronously with the data source to fetch or save the suggestion data.
+* It is used internally by the track changes feature whenever a suggestion is loaded, created or deleted.
+*
+* The adapter is optional. You might need to provide it if you are {@glink features/collaboration/track-changes/track-changes-integration}
+* using the track changes feature without real-time collaboration.
+*
+* To set the adapter, overwrite {@link module:track-changes/trackchanges~TrackChanges#adapter the `TrackChanges#adapter` property}.
+*/
 export interface TrackChangesAdapter {
-    /**
-     * Called each time the suggestion data is needed.
-     *
-     * The method should return a promise that resolves with the suggestion data object.
-     *
-     * @param id The ID of the suggestion to get.
-     */
-    getSuggestion(id: string): Promise<SuggestionData>;
-    /**
-     * Called each time a new suggestion is created.
-     *
-     * The method should save the suggestion data in the database
-     * and return a promise that should be resolved when the save is
-     * completed.
-     *
-     * If the promise resolves with an object with the `createdAt` property,
-     * this suggestion property will be updated in the suggestion in the editor.
-     * This lets you update the suggestion data with server-side information.
-     *
-     * The `suggestionData` object does not expect the `authorId` property.
-     * For security reasons, the author of the suggestion should be set
-     * on the server side.
-     *
-     * If `suggestionData.originalSuggestionId` is set, the new suggestion should
-     * have the `authorId` property set to the same as the suggestion with
-     * `originalSuggestionId`. This happens when one user splits
-     * another user's suggestion, creating a new suggestion as a result. See
-     * {@glink features/collaboration/track-changes/track-changes-integration#implementation Track changes integration} guide.
-     *
-     * **Note:** Failure to properly handle this property will result in editor crash in some scenarios.
-     *
-     * In any other case, use the current (local) user to set `authorId`.
-     *
-     * The `suggestionData` object does not expect the `createdAt` property either.
-     * You should use the server-side time generator to ensure that all users
-     * see the same date.
-     *
-     * It is recommended to stringify `suggestionData.attributes` value to JSON and save it as a string in your database,
-     * and then to parse the strings when loading suggestions.
-     */
-    addSuggestion(suggestionData: AddSuggestionInput): Promise<SuggestionData>;
-    /**
-     * Called each time the suggestion properties change.
-     *
-     * The method should update the suggestion properties in the database
-     * and return a promise that should be resolved when the save is
-     * completed.
-     *
-     * Keep in mind that the `data` parameter only contains those
-     * properties of a suggestion which changed.
-     */
-    updateSuggestion(id: string, suggestionData: UpdateSuggestionInput): Promise<void>;
+	/**
+	* Called each time the suggestion data is needed.
+	*
+	* The method should return a promise that resolves with the suggestion data object.
+	*
+	* @param id The ID of the suggestion to get.
+	*/
+	getSuggestion(id: string): Promise<SuggestionData>;
+	/**
+	* Called each time a new suggestion is created.
+	*
+	* The method should save the suggestion data in the database
+	* and return a promise that should be resolved when the save is
+	* completed.
+	*
+	* If the promise resolves with an object with the `createdAt` property,
+	* this suggestion property will be updated in the suggestion in the editor.
+	* This lets you update the suggestion data with server-side information.
+	*
+	* The `suggestionData` object does not expect the `authorId` property.
+	* For security reasons, the author of the suggestion should be set
+	* on the server side.
+	*
+	* If `suggestionData.originalSuggestionId` is set, the new suggestion should
+	* have the `authorId` property set to the same as the suggestion with
+	* `originalSuggestionId`. This happens when one user splits
+	* another user's suggestion, creating a new suggestion as a result. See
+	* {@glink features/collaboration/track-changes/track-changes-integration#implementation Track changes integration} guide.
+	*
+	* **Note:** Failure to properly handle this property will result in editor crash in some scenarios.
+	*
+	* In any other case, use the current (local) user to set `authorId`.
+	*
+	* The `suggestionData` object does not expect the `createdAt` property either.
+	* You should use the server-side time generator to ensure that all users
+	* see the same date.
+	*
+	* It is recommended to stringify `suggestionData.attributes` value to JSON and save it as a string in your database,
+	* and then to parse the strings when loading suggestions.
+	*/
+	addSuggestion(suggestionData: AddSuggestionInput): Promise<SuggestionData>;
+	/**
+	* Called each time the suggestion properties change.
+	*
+	* The method should update the suggestion properties in the database
+	* and return a promise that should be resolved when the save is
+	* completed.
+	*
+	* Keep in mind that the `data` parameter only contains those
+	* properties of a suggestion which changed.
+	*/
+	updateSuggestion(id: string, suggestionData: UpdateSuggestionInput): Promise<void>;
 }
 export interface SuggestionData extends SuggestionJSON {
-    /**
-     * Original suggestion ID from which the current one was split.
-     */
-    originalSuggestionId?: string | null;
+	/**
+	* Original suggestion ID from which the current one was split.
+	*/
+	originalSuggestionId?: string | null;
 }
-export type AddSuggestionInput = Omit<SuggestionData, 'authorId' | 'createdAt'>;
-export type UpdateSuggestionInput = Partial<Pick<SuggestionJSON, 'hasComments' | 'attributes'>> & {
-    state?: 'open' | 'accepted' | 'rejected';
+export type AddSuggestionInput = Omit<SuggestionData, "authorId" | "createdAt">;
+export type UpdateSuggestionInput = Partial<Pick<SuggestionJSON, "hasComments" | "attributes">> & {
+	state?: "open" | "accepted" | "rejected";
 };

package/dist/trackchangesconfig.d.ts

@@ -1,110 +1,143 @@
 /**
- * @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 track-changes/trackchangesconfig
- * @publicApi
- */
-import { type SuggestionThreadView } from './ui/view/suggestionthreadview.js';
-import { type SuggestionView } from './ui/view/suggestionview.js';
+* @module track-changes/trackchangesconfig
+* @publicApi
+*/
+import { type SuggestionThreadView } from "./ui/view/suggestionthreadview.js";
+import { type SuggestionView } from "./ui/view/suggestionview.js";
 /**
- * The configuration of the track changes feature.
- *
- * Example:
- *
- * ```ts
- * ClassicEditor
- * 	.create( {
- * 		// Track changes feature configuration.
- * 		trackChanges: {
- * 		// Do not allow users to comment suggestions (default is `false`).
- * 		disableComments: true,
- * 		// Do not track styling and formatting changes (default is `default`).
- * 		trackFormatChanges: 'never',
- * 		// Merges suggestion changes inside a block. (default is `true`).
- * 		mergeNestedSuggestions: true
- * 		}
- * 	} )
- * 	.then( ... )
- * 	.catch( ... );
- * ```
- *
- * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
- */
+* The configuration of the track changes feature.
+*
+* Example:
+*
+* ```ts
+* ClassicEditor
+* 	.create( {
+* 		// Track changes feature configuration.
+* 		trackChanges: {
+* 		// Do not allow users to comment suggestions (default is `false`).
+* 		disableComments: true,
+* 		// Do not track styling and formatting changes (default is `default`).
+* 		trackFormatChanges: 'never',
+* 		// Merges suggestion changes inside a block. (default is `true`).
+* 		mergeNestedSuggestions: true
+* 		}
+* 	} )
+* 	.then( ... )
+* 	.catch( ... );
+* ```
+*
+* See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
+*/
 export interface TrackChangesConfig {
-    /**
-     * A property that specifies if the comments for suggestions are enabled or disabled.
-     * When the option is set to `true`, the comment thread UI for suggestions will be hidden
-     * and commenting suggestions will be disabled.
-     *
-     * Suggestion thread views will be marked with the additional `ck-suggestion--disabled-comments` class when the suggestion comments
-     * are disabled.
-     *
-     * @default false
-     */
-    disableComments?: boolean;
-    /**
-     * A property that specifies whether formatting changes should be tracked.
-     *
-     * Formatting changes are all changes other than insertions and deletions, including: styling, structure, widgets properties, etc.
-     *
-     * By default, formatting changes are tracked. However, if you make a formatting change inside your own insertion suggestion, it
-     * is immediately applied, without creating a suggestion.
-     *
-     * Possible values are:
-     *
-     * * `'default'` - format changes are tracked, but when made inside your own insertion suggestion, they will be immediately applied.
-     * * `'always'` - format changes will always be tracked, even inside your own insertion suggestion.
-     * * `'never'` - format changes will never be tracked (suggestions for such changes will not be created).
-     *
-     * @default 'default'
-     */
-    trackFormatChanges?: 'never' | 'default' | 'always';
-    /**
-     * Specifies whether suggestions on an object (e.g. image, table) should be automatically merged
-     * with suggestions inside the object (e.g. image caption, table cell).
-     *
-     * For example, when set to `true`, creating a table and writing some text inside the table will result in one suggestion.
-     * When set to `false`, it will be two separate suggestions, one for the inserted table and one for the inserted text.
-     *
-     * Keep in mind that only suggestions from the same author and of the same type are merged this way.
-     *
-     * @default true
-     */
-    mergeNestedSuggestions?: boolean;
-    /**
-     * A view class to be used to create suggestion thread views.
-     *
-     * {@link module:track-changes/ui/view/suggestionthreadview~SuggestionThreadView} is used by default
-     *  when this property is not set.
-     */
-    SuggestionThreadView?: typeof SuggestionThreadView;
-    /**
-     * A view class to be used to create the suggestion view.
-     *
-     * {@link module:track-changes/ui/view/suggestionview~SuggestionView} is used by default when this property is not set.
-     */
-    SuggestionView?: typeof SuggestionView;
-    /**
-     * Configuration of the track changes preview feature.
-     */
-    preview?: TrackChangesPreviewConfig;
+	/**
+	* A property that specifies if the comments for suggestions are enabled or disabled.
+	* When the option is set to `true`, the comment thread UI for suggestions will be hidden
+	* and commenting suggestions will be disabled.
+	*
+	* Suggestion thread views will be marked with the additional `ck-suggestion--disabled-comments` class when the suggestion comments
+	* are disabled.
+	*
+	* @default false
+	*/
+	disableComments?: boolean;
+	/**
+	* A property that specifies whether formatting changes should be tracked.
+	*
+	* Formatting changes are all changes other than insertions and deletions, including: styling, structure, widgets properties, etc.
+	*
+	* By default, formatting changes are tracked. However, if you make a formatting change inside your own insertion suggestion, it
+	* is immediately applied, without creating a suggestion.
+	*
+	* Possible values are:
+	*
+	* * `'default'` - format changes are tracked, but when made inside your own insertion suggestion, they will be immediately applied.
+	* * `'always'` - format changes will always be tracked, even inside your own insertion suggestion.
+	* * `'never'` - format changes will never be tracked (suggestions for such changes will not be created).
+	*
+	* @default 'default'
+	*/
+	trackFormatChanges?: "never" | "default" | "always";
+	/**
+	* Specifies whether suggestions on an object (e.g. image, table) should be automatically merged
+	* with suggestions inside the object (e.g. image caption, table cell).
+	*
+	* For example, when set to `true`, creating a table and writing some text inside the table will result in one suggestion.
+	* When set to `false`, it will be two separate suggestions, one for the inserted table and one for the inserted text.
+	*
+	* Keep in mind that only suggestions from the same author and of the same type are merged this way.
+	*
+	* @default true
+	*/
+	mergeNestedSuggestions?: boolean;
+	/**
+	* A view class to be used to create suggestion thread views.
+	*
+	* {@link module:track-changes/ui/view/suggestionthreadview~SuggestionThreadView} is used by default
+	*  when this property is not set.
+	*/
+	SuggestionThreadView?: typeof SuggestionThreadView;
+	/**
+	* A view class to be used to create the suggestion view.
+	*
+	* {@link module:track-changes/ui/view/suggestionview~SuggestionView} is used by default when this property is not set.
+	*/
+	SuggestionView?: typeof SuggestionView;
+	/**
+	* Controls if and how the suggestion annotation displays information that the suggestion was generated by AI.
+	*
+	* Possible values:
+	*
+	* * `'pill'` - shows an "AI-generated" pill in the suggestion balloon while preserving the original author's identity.
+	* * `'author'` - swaps the author shown in the suggestion view (name + avatar) for a view-only AI identity.
+	* The original author's ID is still preserved in suggestion's data.
+	* The view-only identity can be customized via {@link #aiAuthor}.
+	* * `null` - the AI source is hidden (default).
+	*
+	* @default null
+	*/
+	showAISource?: "pill" | "author" | null;
+	/**
+	* The view-only identity used to render AI-sourced suggestions when {@link #showAISource} is set to `'author'`.
+	*
+	* This is a view-only override. The persisted author of the suggestion is not affected.
+	*
+	* Defaults to a built-in `AI Assistant` identity when this option is not provided.
+	*/
+	aiAuthor?: {
+		/**
+		* Display name used in the suggestion view.
+		*
+		* @default 'AI Assistant'
+		*/
+		name?: string;
+		/**
+		* URL to an avatar image. When not provided, a default AI icon is shown.
+		*/
+		avatar?: string;
+	};
+	/**
+	* Configuration of the track changes preview feature.
+	*/
+	preview?: TrackChangesPreviewConfig;
 }
 export interface TrackChangesPreviewConfig {
-    /**
-     * A callback function that allows for modifying the structure of the
-     * {@link module:track-changes/trackchangespreview~TrackChangesPreview track changes preview} container.
-     *
-     * The callback receives the container element (`.ck-track-changes-preview`) and an array of root elements.
-     *
-     * * If the editor only has one root, there's only one element in the array.
-     * * If the editor has multiple roots, the there's one element per root. They are ordered either by `order`
-     * root attribute or, if it's not present, by DOM order.
-     *
-     * The callback should append all array elements to the container, but can also add custom classes, elements in between etc.
-     *
-     * The default callback simply appends all elements to the container in the order they are provided.
-     */
-    renderFunction?: (container: HTMLElement, elements: Array<HTMLElement>) => void;
+	/**
+	* A callback function that allows for modifying the structure of the
+	* {@link module:track-changes/trackchangespreview~TrackChangesPreview track changes preview} container.
+	*
+	* The callback receives the container element (`.ck-track-changes-preview`) and an array of root elements.
+	*
+	* * If the editor only has one root, there's only one element in the array.
+	* * If the editor has multiple roots, the there's one element per root. They are ordered either by `order`
+	* root attribute or, if it's not present, by DOM order.
+	*
+	* The callback should append all array elements to the container, but can also add custom classes, elements in between etc.
+	*
+	* The default callback simply appends all elements to the container in the order they are provided.
+	*/
+	renderFunction?: (container: HTMLElement, elements: Array<HTMLElement>) => void;
 }