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

package/dist/suggestion.d.ts

@@ -1,292 +1,294 @@
 /**
- * @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/suggestion
- * @publicApi
- */
-import { ModelElement, type Marker, type Model, type ModelRange, type ModelItem } from '@ckeditor/ckeditor5-engine';
-import type { User } from '@ckeditor/ckeditor5-collaboration-core';
-import type { CommentThread } from '@ckeditor/ckeditor5-comments';
-import type { SuggestionFormatData, SuggestionAttributeData } from './trackchangesediting.js';
-declare const Suggestion_base: {
-    new (): import("@ckeditor/ckeditor5-utils").Observable;
-    prototype: import("@ckeditor/ckeditor5-utils").Observable;
-};
+* @module track-changes/suggestion
+* @publicApi
+*/
+import { ModelElement, type Marker, type Model, type ModelRange, type ModelItem } from "@ckeditor/ckeditor5-engine";
+import { type ObservableMixinConstructor } from "@ckeditor/ckeditor5-utils";
+import type { User } from "@ckeditor/ckeditor5-collaboration-core";
+import type { CommentThread } from "@ckeditor/ckeditor5-comments";
+import type { SuggestionFormatData, SuggestionAttributeData } from "./trackchangesediting.js";
+declare const _SuggestionBase: ObservableMixinConstructor;
 /**
- * Represents a singular suggestion that is tracked by track changes plugin.
- *
- * `Suggestion` instances are created and handled by {@link module:track-changes/trackchanges~TrackChanges track changes plugin}.
- */
-export declare class Suggestion extends /* #__PURE__ -- @preserve */ Suggestion_base {
-    /**
-     * Suggestion ID.
-     */
-    readonly id: string;
-    /**
-     * Suggestion type.
-     */
-    type: SuggestionType;
-    /**
-     * Suggestion sub-type.
-     *
-     * This is an additional identifier for suggestions. Two suggestions of the same type may have different sub-types to differentiate
-     * suggestions behavior and handle interactions between suggestions.
-     *
-     * Sub-type is used for:
-     *
-     *  * suggestions joining (only suggestions with the same sub-type can be joined),
-     *  * suggestions custom callbacks (fired when adding, deleting and joining suggestions).
-     */
-    subType: string | null;
-    /**
-     * The author of the change marked by the suggestion.
-     */
-    author: User;
-    /**
-     * The user which saved the suggestion data in the database.
-     *
-     * Usually the same as author but may be different in some cases (e.g. when suggestion was added from an external source).
-     */
-    creator: User;
-    /**
-     * The flag indicating whether the suggestion comes from an external source.
-     */
-    isExternal: boolean;
-    /**
-     * Additional suggestion data.
-     */
-    data: SuggestionFormatData | SuggestionAttributeData | null;
-    /**
-     * Date when the suggestion was saved in the database.
-     */
-    createdAt: Date | null;
-    /**
-     * Date when the change marked by the suggestion was made.
-     *
-     * Usually the same as {@link #createdAt `createdAt`} but may be different in some cases
-     * (e.g. when suggestion was added from an external source).
-     *
-     * @observable
-     */
-    authoredAt: Date | null;
-    /**
-     * Custom suggestion attributes. See also {@link #setAttribute} and {@link #removeAttribute}.
-     *
-     * @observable
-     */
-    attributes: {
-        [k: string]: unknown;
-    };
-    /**
-     * Previous suggestion in suggestions chain.
-     *
-     * Chained suggestions should be handled as one entity.
-     *
-     * @observable
-     */
-    previous: Suggestion | null;
-    /**
-     * Next suggestion in suggestions chain.
-     *
-     * Chained suggestions should be handled as one entity.
-     *
-     * @observable
-     */
-    next: Suggestion | null;
-    /**
-     * Comment thread model for comments added to this suggestion.
-     *
-     * @observable
-     */
-    commentThread: CommentThread | null;
-    constructor(model: Model, options: SuggestionOptions);
-    /**
-     * The first (most-previous) suggestion in this suggestion chain.
-     */
-    get head(): Suggestion;
-    /**
-     * Informs whether suggestion has at least one comment.
-     */
-    get hasComments(): boolean;
-    /**
-     * Informs whether the suggestion is a multi-range suggestion or a single-range suggestion.
-     *
-     * This is evaluated basing on the marker name belonging to this suggestion.
-     * Even if only one marker belongs to the suggestion at a given time it can still be a multi range suggestion.
-     */
-    get isMultiRange(): boolean;
-    /**
-     * Informs whether the suggestion is still in the editor content.
-     *
-     * Returns `true` if there is at least one marker suggestion in the editor content.
-     */
-    get isInContent(): boolean;
-    /**
-     * Binds given marker name to this suggestion.
-     */
-    addMarkerName(markerName: string): void;
-    /**
-     * Returns all names of markers belonging to this suggestion.
-     */
-    getMarkerNames(): Array<string>;
-    /**
-     * Returns all markers belonging to this suggestion.
-     */
-    getMarkers(): Array<Marker>;
-    /**
-     * Returns the first marker belonging to this suggestion, i.e the first marker that was added to this suggestion
-     * and not removed yet.
-     *
-     * This method is useful if you know that the suggestion has only one marker and want to process it.
-     */
-    getFirstMarker(): Marker | null;
-    /**
-     * Removes all markers from the suggestion and the editor content.
-     */
-    removeMarkers(): void;
-    /**
-     * Removes marker with the given name from the suggestion and the editor content.
-     */
-    removeMarker(markerName: string): void;
-    /**
-     * Adds a new range to this suggestion. It is assumed that the suggestion is a multi-range suggestion.
-     *
-     * A marker name is generated from this suggestion's properties and a marker with that name is created and set to a given `range`.
-     */
-    addRange(range: ModelRange): void;
-    /**
-     * Checks if given `range` is intersecting with any of the ranges of markers belonging to this suggestion.
-     */
-    isIntersectingWithRange(range: ModelRange): boolean;
-    /**
-     * Returns all ranges of all markers belonging to this suggestion.
-     */
-    getRanges(): Array<ModelRange>;
-    /**
-     * Returns all {@link module:engine/model/item~ModelItem model items} that are in this suggestion.
-     */
-    getItems(): Array<ModelItem>;
-    /**
-     * Returns the first range belonging to this suggestion, i.e. the range of the first marker that was added to
-     * this suggestion and not removed yet.
-     *
-     * This method is useful if you know that the suggestion has only one marker and want to process its range.
-     */
-    getFirstRange(): ModelRange | null;
-    /**
-     * Returns the model element contained in the suggestion.
-     *
-     * A {@link module:engine/model/element~ModelElement model element} is considered as contained if there is exactly
-     * one range in the suggestion, and that range contains exactly one element.
-     *
-     * Returns `null` if there is no contained element.
-     */
-    getContainedElement(): ModelElement | null;
-    /**
-     * Accepts the suggestion.
-     */
-    accept(): void;
-    /**
-     * Discards the suggestion.
-     */
-    discard(): void;
-    /**
-     * Returns all suggestions that are in this suggestion chain.
-     */
-    getAllAdjacentSuggestions(): Array<Suggestion>;
-    /**
-     * Adds suggestion attribute.
-     *
-     * Suggestion attributes are custom data that can be set and used by features
-     * built around suggestions. Use it to store your feature data with other suggestion data.
-     *
-     * ```ts
-     * suggestion.setAttribute( 'isImportant', true );
-     * ```
-     *
-     * You can group multiple values in an object, using dot notation:
-     *
-     * ```ts
-     * suggestion.setAttribute( 'customData.type', 'image' );
-     * suggestion.setAttribute( 'customData.src', 'foo.jpg' );
-     * ```
-     *
-     * Attributes set on the suggestion can be accessed through `attribute` property:
-     *
-     * ```ts
-     * const isImportant = suggestion.attributes.isImportant;
-     * const type = suggestion.attributes.customData.type;
-     * ```
-     *
-     * You can also observe `attributes` property or bind other properties to it:
-     *
-     * ```ts
-     * myObj.bind( 'customData' ).to( suggestion, 'attributes', attributes => attributes.customData );
-     * ```
-     *
-     * Whenever `setAttribute()` or `removeAttribute()` is called, `attributes` property
-     * is re-set and observables are refreshed.
-     */
-    setAttribute(name: string, value: unknown): void;
-    /**
-     * Removes suggestion attribute.
-     *
-     * See also {@link #setAttribute}
-     */
-    removeAttribute(name: string): void;
-    toJSON(): SuggestionJSON;
-    /**
-     * Returns a random string that can be used as additional identifier for the marker name for suggestions that are multi range.
-     */
-    static getMultiRangeId(): string;
+* Represents a singular suggestion that is tracked by track changes plugin.
+*
+* `Suggestion` instances are created and handled by {@link module:track-changes/trackchanges~TrackChanges track changes plugin}.
+*/
+export declare class Suggestion extends _SuggestionBase {
+	/**
+	* Suggestion ID.
+	*/
+	readonly id: string;
+	/**
+	* Suggestion type.
+	*/
+	type: SuggestionType;
+	/**
+	* Suggestion sub-type.
+	*
+	* This is an additional identifier for suggestions. Two suggestions of the same type may have different sub-types to differentiate
+	* suggestions behavior and handle interactions between suggestions.
+	*
+	* Sub-type is used for:
+	*
+	*  * suggestions joining (only suggestions with the same sub-type can be joined),
+	*  * suggestions custom callbacks (fired when adding, deleting and joining suggestions).
+	*/
+	subType: string | null;
+	/**
+	* The author of the change marked by the suggestion.
+	*/
+	author: User;
+	/**
+	* The user which saved the suggestion data in the database.
+	*
+	* Usually the same as author but may be different in some cases (e.g. when suggestion was added from an external source).
+	*/
+	creator: User;
+	/**
+	* Additional suggestion data.
+	*/
+	data: SuggestionFormatData | SuggestionAttributeData | null;
+	/**
+	* Date when the suggestion was saved in the database.
+	*/
+	createdAt: Date | null;
+	/**
+	* Date when the change marked by the suggestion was made.
+	*
+	* Usually the same as {@link #createdAt `createdAt`} but may be different in some cases
+	* (e.g. when suggestion was added from an external source).
+	*
+	* @observable
+	*/
+	authoredAt: Date | null;
+	/**
+	* Custom suggestion attributes. See also {@link #setAttribute} and {@link #removeAttribute}.
+	*
+	* @observable
+	*/
+	attributes: {
+		[k: string]: unknown;
+	};
+	/**
+	* Previous suggestion in suggestions chain.
+	*
+	* Chained suggestions should be handled as one entity.
+	*
+	* @observable
+	*/
+	previous: Suggestion | null;
+	/**
+	* Next suggestion in suggestions chain.
+	*
+	* Chained suggestions should be handled as one entity.
+	*
+	* @observable
+	*/
+	next: Suggestion | null;
+	/**
+	* Comment thread model for comments added to this suggestion.
+	*
+	* @observable
+	*/
+	commentThread: CommentThread | null;
+	constructor(model: Model, options: SuggestionOptions);
+	/**
+	* The flag indicating whether the suggestion comes from an external source.
+	*/
+	get isExternal(): boolean;
+	/**
+	* AI source identifier when the suggestion was produced by an AI feature, otherwise `null`.
+	*/
+	get aiSource(): string | null;
+	/**
+	* The first (most-previous) suggestion in this suggestion chain.
+	*/
+	get head(): Suggestion;
+	/**
+	* Informs whether suggestion has at least one comment.
+	*/
+	get hasComments(): boolean;
+	/**
+	* Informs whether the suggestion is a multi-range suggestion or a single-range suggestion.
+	*
+	* This is evaluated basing on the marker name belonging to this suggestion.
+	* Even if only one marker belongs to the suggestion at a given time it can still be a multi range suggestion.
+	*/
+	get isMultiRange(): boolean;
+	/**
+	* Informs whether the suggestion is still in the editor content.
+	*
+	* Returns `true` if there is at least one marker suggestion in the editor content.
+	*/
+	get isInContent(): boolean;
+	/**
+	* Binds given marker name to this suggestion.
+	*/
+	addMarkerName(markerName: string): void;
+	/**
+	* Returns all names of markers belonging to this suggestion.
+	*/
+	getMarkerNames(): Array<string>;
+	/**
+	* Returns all markers belonging to this suggestion.
+	*/
+	getMarkers(): Array<Marker>;
+	/**
+	* Returns the first marker belonging to this suggestion, i.e the first marker that was added to this suggestion
+	* and not removed yet.
+	*
+	* This method is useful if you know that the suggestion has only one marker and want to process it.
+	*/
+	getFirstMarker(): Marker | null;
+	/**
+	* Removes all markers from the suggestion and the editor content.
+	*/
+	removeMarkers(): void;
+	/**
+	* Removes marker with the given name from the suggestion and the editor content.
+	*/
+	removeMarker(markerName: string): void;
+	/**
+	* Adds a new range to this suggestion. It is assumed that the suggestion is a multi-range suggestion.
+	*
+	* A marker name is generated from this suggestion's properties and a marker with that name is created and set to a given `range`.
+	*/
+	addRange(range: ModelRange): void;
+	/**
+	* Checks if given `range` is intersecting with any of the ranges of markers belonging to this suggestion.
+	*/
+	isIntersectingWithRange(range: ModelRange): boolean;
+	/**
+	* Returns all ranges of all markers belonging to this suggestion.
+	*/
+	getRanges(): Array<ModelRange>;
+	/**
+	* Returns all {@link module:engine/model/item~ModelItem model items} that are in this suggestion.
+	*/
+	getItems(): Array<ModelItem>;
+	/**
+	* Returns the first range belonging to this suggestion, i.e. the range of the first marker that was added to
+	* this suggestion and not removed yet.
+	*
+	* This method is useful if you know that the suggestion has only one marker and want to process its range.
+	*/
+	getFirstRange(): ModelRange | null;
+	/**
+	* Returns the model element contained in the suggestion.
+	*
+	* A {@link module:engine/model/element~ModelElement model element} is considered as contained if there is exactly
+	* one range in the suggestion, and that range contains exactly one element.
+	*
+	* Returns `null` if there is no contained element.
+	*/
+	getContainedElement(): ModelElement | null;
+	/**
+	* Accepts the suggestion.
+	*/
+	accept(): void;
+	/**
+	* Discards the suggestion.
+	*/
+	discard(): void;
+	/**
+	* Returns all suggestions that are in this suggestion chain.
+	*/
+	getAllAdjacentSuggestions(): Array<Suggestion>;
+	/**
+	* Adds suggestion attribute.
+	*
+	* Suggestion attributes are custom data that can be set and used by features
+	* built around suggestions. Use it to store your feature data with other suggestion data.
+	*
+	* ```ts
+	* suggestion.setAttribute( 'isImportant', true );
+	* ```
+	*
+	* You can group multiple values in an object, using dot notation:
+	*
+	* ```ts
+	* suggestion.setAttribute( 'customData.type', 'image' );
+	* suggestion.setAttribute( 'customData.src', 'foo.jpg' );
+	* ```
+	*
+	* Attributes set on the suggestion can be accessed through `attribute` property:
+	*
+	* ```ts
+	* const isImportant = suggestion.attributes.isImportant;
+	* const type = suggestion.attributes.customData.type;
+	* ```
+	*
+	* You can also observe `attributes` property or bind other properties to it:
+	*
+	* ```ts
+	* myObj.bind( 'customData' ).to( suggestion, 'attributes', attributes => attributes.customData );
+	* ```
+	*
+	* Whenever `setAttribute()` or `removeAttribute()` is called, `attributes` property
+	* is re-set and observables are refreshed.
+	*/
+	setAttribute(name: string, value: unknown): void;
+	/**
+	* Removes suggestion attribute.
+	*
+	* See also {@link #setAttribute}
+	*/
+	removeAttribute(name: string): void;
+	toJSON(): SuggestionJSON;
+	/**
+	* Returns a random string that can be used as additional identifier for the marker name for suggestions that are multi range.
+	*/
+	static getMultiRangeId(): string;
 }
 export interface SuggestionOptions {
-    id: string;
-    type: SuggestionType;
-    subType: string | null;
-    attributes: {
-        [k: string]: unknown;
-    };
-    author: User;
-    creator: User;
-    onAccept: Function;
-    onDiscard: Function;
-    onAttributesChange: Function;
-    originalSuggestionId?: string | null;
+	id: string;
+	type: SuggestionType;
+	subType: string | null;
+	attributes: {
+		[k: string]: unknown;
+	};
+	author: User;
+	creator: User;
+	onAccept: Function;
+	onDiscard: Function;
+	onAttributesChange: Function;
+	originalSuggestionId?: string | null;
 }
 export interface SuggestionJSON {
-    /**
-     * Suggestion ID.
-     */
-    id: string;
-    /**
-     * Contains the information about the type and subtype of the suggestion.
-     */
-    type: string;
-    /**
-     * The ID of the author.
-     */
-    authorId: string;
-    /**
-     * Date when the suggestion was saved in the database.
-     */
-    createdAt: Date | null;
-    /**
-     * Informs whether suggestion has at least one comment.
-     */
-    hasComments?: boolean;
-    /**
-     * Additional suggestion data.
-     */
-    data?: SuggestionFormatData | SuggestionAttributeData | null;
-    /**
-     * Custom suggestion attributes.
-     */
-    attributes: {
-        [k: string]: unknown;
-    };
+	/**
+	* Suggestion ID.
+	*/
+	id: string;
+	/**
+	* Contains the information about the type and subtype of the suggestion.
+	*/
+	type: string;
+	/**
+	* The ID of the author.
+	*/
+	authorId: string;
+	/**
+	* Date when the suggestion was saved in the database.
+	*/
+	createdAt: Date | null;
+	/**
+	* Informs whether suggestion has at least one comment.
+	*/
+	hasComments?: boolean;
+	/**
+	* Additional suggestion data.
+	*/
+	data?: SuggestionFormatData | SuggestionAttributeData | null;
+	/**
+	* Custom suggestion attributes.
+	*/
+	attributes: {
+		[k: string]: unknown;
+	};
 }
-export type SuggestionType = 'insertion' | 'deletion' | 'formatInline' | 'formatBlock' | 'attribute';
+export type SuggestionType = "insertion" | "deletion" | "formatInline" | "formatBlock" | "attribute";
 export {};