@ckeditor/ckeditor5-comments/src/comments/addcommentthreadcommand.d.ts

Collaborative comments feature for CKEditor 5.

/**
 * @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 comments/comments/addcommentthreadcommand
 * @publicApi
 */
import { Command, type Editor } from 'ckeditor5/src/core.js';
import type { ModelRange } from 'ckeditor5/src/engine.js';
/**
 * Adds a new comment marker, what also automatically adds a corresponding {@link module:comments/comments/commentsrepository~CommentThread}
 * in {@link module:comments/comments/commentsrepository~CommentsRepository}.
 *
 * By default, this command creates an empty comment thread on content selected in the editor.
 * The related marker is "local only", is not managed using operations, and it does not affect editor data.
 * The user is expected to write and submit the first comment. When first comment is submitted, the marker is changed to use operations,
 * which means that it is saved in data, and is propagated to other users in real-time-collaboration. This happens outside of this command.
 *
 * You can specify custom ranges by passing the `ranges` option to create the comment thread on specified content
 * instead of the current selection.
 *
 * You can provide content for the first comment using the `comment` option. Then, the created thread will contain this initial comment.
 * The thread will be automatically submitted, and the related marker will be propagated to other users and will affect editor data.
 *
 * Usage:
 * ```ts
 * // Create a draft comment thread on the current selection.
 * // If `threadId` is not specified, `addCommentThread()` will generate a unique ID and use it:
 * editor.execute( 'addCommentThread' );
 *
 * // Create a draft comment thread on custom ranges:
 * editor.execute( 'addCommentThread', { ranges: [ myRange1, myRange2 ] } );
 *
 * // Create a public comment thread with an initial comment:
 * editor.execute( 'addCommentThread', { comment: 'Initial comment text' } );
 * ```
 *
 * A comment thread can be added only on ranges that contain content. If the current document selection, or passed ranges
 * do not contain any content, the command will throw an error.
 *
 * You can use {@link #hasContent} observable property to check whether the current selection has any content.
 */
export declare class AddCommentThreadCommand extends Command {
    /**
     * Indicates whether the current selection contains content.
     *
     * @observable
     */
    hasContent: boolean;
    /**
     * @inheritDoc
     */
    constructor(editor: Editor);
    /**
     * @inheritDoc
     */
    refresh(): void;
    /**
     * Executes the command to add a new comment thread.
     *
     * @fires execute
     * @param options Options for executed command.
     * @param options.threadId Id of comment marker that will be added. If not provided, a unique id will be generated.
     * @param options.ranges Array of ranges to use instead of current selection. If not provided,
     * the current selection will be used.
     * @param options.comment Initial comment text. If provided, the created comment thread will contain this comment as its first entry.
     */
    execute({ threadId, ranges, comment }?: {
        threadId?: string;
        ranges?: Array<ModelRange>;
        comment?: string;
    }): void;
}