@ckeditor/ckeditor5-comments 41.3.1 → 41.4.0-alpha.0

package/dist/types/comments/ui/view/commentsarchiveview.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module comments/comments/ui/view/commentslistview
+ */
+import { View, type ViewCollection } from 'ckeditor5/src/ui.js';
+import { type Locale } from 'ckeditor5/src/utils.js';
+import type AnnotationView from '../../../annotations/view/annotationview.js';
+/**
+ * A view representing the content of comments archive.
+ */
+export default class CommentsArchiveView extends View {
+    /**
+     * The flag indicating whether there are items to display in the comments archive.
+     *
+     * @observable
+     */
+    isEmpty: boolean;
+    /**
+     * @param locale The localization service instance.
+     * @param annotationViews Resolved comment thread annotation views to render inside the comments archive.
+     */
+    constructor(locale: Locale, annotationViews: ViewCollection<AnnotationView>);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * @inheritDoc
+     */
+    focus(): void;
+}

package/dist/types/comments/ui/view/commentslistview.d.ts

@@ -0,0 +1,104 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module comments/comments/ui/view/commentslistview
+ */
+import { View, type ViewCollection } from 'ckeditor5/src/ui.js';
+import { type Locale } from 'ckeditor5/src/utils.js';
+import type { CommentThread } from '../../commentsrepository.js';
+import type CommentView from './commentview.js';
+import type { CommentThreadConfig } from '../../../config.js';
+/**
+ * A view representing the list of comments. It should be used as a part of the comment thread view.
+ */
+export default class CommentsListView extends View {
+    locale: Locale;
+    /**
+     * Informs whether the list contains any comment view that is in the editing mode.
+     *
+     * @observable
+     */
+    hasDirtyComment: boolean;
+    /**
+     * Number of comments in the list.
+     *
+     * @observable
+     */
+    length: number;
+    /**
+     * Informs whether the comments list view is in the active state ("highlighted").
+     * Comment list view is in that state when it is focused or it was activated by the user in any different way.
+     *
+     * @observable
+     */
+    isActive: boolean;
+    /**
+     * View collection which holds all comment views to be displayed.
+     * It may also contain collapsed count view if the comments list view is collapsed and some comment views are hidden.
+     *
+     * @readonly
+     */
+    readonly visibleViews: ViewCollection;
+    /**
+     * View collection which holds all comment views created for given comment thread.
+     *
+     * @readonly
+     */
+    readonly commentViews: ViewCollection;
+    /**
+     * Comment view used to display information that comment has been resolved.
+     *
+     * @readonly
+     */
+    resolvedCommentView: CommentView | null;
+    /**
+     * @param locale The localization service instance.
+     * @param model The model on which the view will base.
+     * @param config Additional view configuration.
+     */
+    constructor(locale: Locale, model: CommentThread, config: CommentThreadConfig);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * Focuses the view.
+     */
+    focus(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Refreshes the list of the visible views.
+     *
+     * When doing so, it performs a minimal amount of changes, so that views are not re-added, which might cause undesirable effects
+     * like focus loss or glitches due to CSS animations.
+     *
+     * The comments list may be collapsed or expanded:
+     *
+     * * it is expanded, if it {@link ~#isActive is active},
+     * * it is expanded, if {@link module:comments/comments/commentsrepository~CommentThread#weight comment thread weight}
+     * is lower than allowed (`config.comments.maxThreadTotalWeight`),
+     * * it is expanded, if it {@link ~#hasDirtyComment has any comments in edit mode},
+     * * it is collapsed, if neither of above is true.
+     *
+     * When comments list is in collapsed state, it displays at most `config.comments.maxCommentsWhenCollapsed` comment views:
+     *
+     * * first comment view,
+     * * {@link ~#_collapsedCommentsView collapsed comments counter} (if there are any hidden views),
+     * * appropriate number of the comments from the bottom of the thread.
+     *
+     * All the comments are also {@link module:comments/comments/ui/view/basecommentview~BaseCommentView#collapse set to collapsed state}.
+     *
+     * When comments list in in expanded state, it displays all comment views for all comments. All the comments are also
+     * {@link module:comments/comments/ui/view/basecommentview~BaseCommentView#expand set to expanded state}.
+     */
+    refreshVisibleViews(): void;
+}

package/dist/types/comments/ui/view/commentthreadheaderview.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module comments/comments/ui/view/commentthreadheaderview
+ */
+import { View, ButtonView } from 'ckeditor5/src/ui.js';
+import type { Locale } from 'ckeditor5/src/utils.js';
+import type { CommentThread } from '../../commentsrepository.js';
+export declare const MAX_CONTENT_LENGTH = 150;
+/**
+ * A view for the comment thread header.
+ */
+export default class CommentThreadHeaderView extends View {
+    locale: Locale;
+    /**
+     * Defines whether the context value exists.
+     *
+     * @observable
+     */
+    hasContext: boolean;
+    /**
+     * Context value to display in the header.
+     *
+     * @observable
+     */
+    contextValue: string;
+    /**
+     * Button view for the button which reopen the comment thread.
+     */
+    reopenButtonView: ButtonView;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale: Locale, model: CommentThread);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+}
+/**
+ * Fired when a user performed an action that should lead to reopen the resolved comment thread.
+ *
+ * @eventName ~CommentThreadHeaderView#reopenCommentThread
+ */
+export type UIReopenCommentThreadEvent = {
+    name: 'reopenCommentThread';
+    args: [id: string];
+};

package/dist/types/comments/ui/view/commentthreadinputview.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module comments/comments/ui/view/commentthreadinputview
+ */
+import { View } from 'ckeditor5/src/ui.js';
+import CommentInputView from './commentinputview.js';
+import type { Locale } from 'ckeditor5/src/utils.js';
+import type { EditorConfig } from 'ckeditor5/src/core.js';
+import { UserView, type User } from 'ckeditor5-collaboration/src/collaboration-core.js';
+/**
+ * View that represents comment input area for a comment thread. Includes editor, user view and buttons.
+ */
+export default class CommentThreadInputView extends View {
+    /**
+     * Specifies whether the comment input view should be visible (`true`) or hidden (`false`).
+     *
+     * @observable
+     */
+    showInput: boolean;
+    /**
+     * Comment input view.
+     */
+    commentInputView: CommentInputView;
+    /**
+     * User view for the input area. Presents the local user.
+     */
+    userView: UserView;
+    /**
+     * @param locale The localization service instance.
+     * @param localUser Current local user.
+     * @param editorConfig
+     */
+    constructor(locale: Locale, localUser: User, editorConfig: EditorConfig);
+    /**
+     * @inheritDoc
+     */
+    destroy(): Promise<void>;
+}

package/dist/types/comments/ui/view/commentthreadview.d.ts

@@ -0,0 +1,122 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module comments/comments/ui/view/commentthreadview
+ * @publicApi
+ */
+import { type Locale } from 'ckeditor5/src/utils.js';
+import { type User } from 'ckeditor5-collaboration/src/collaboration-core.js';
+import { ButtonView, type TemplateDefinition, type ViewCollection } from 'ckeditor5/src/ui.js';
+import BaseCommentThreadView from './basecommentthreadview.js';
+import type { CommentThread } from '../../commentsrepository.js';
+import type { CommentThreadConfig } from '../../../config.js';
+declare const CommentThreadView_base: import("ckeditor5/src/utils.js").Mixed<typeof BaseCommentThreadView, import("@ckeditor/ckeditor5-collaboration-core/src/utils/confirmmixin.js").ConfirmApi>;
+/**
+ * The default view for comment thread.
+ */
+export default class CommentThreadView extends CommentThreadView_base {
+    isConfirm: boolean;
+    cancelConfirm: () => void;
+    showConfirm: (key: string, element: unknown) => Promise<void>;
+    /**
+     * The locale instance.
+     */
+    readonly locale: Locale;
+    /**
+     * A property used by the template.
+     *
+     * It works as a visual indicator for the user that an action is about to be performed.
+     * The value of this property is used in setting the CSS class.
+     * The property is used when the user interacts with the view.
+     *
+     * @observable
+     */
+    actionIndicator: string | null;
+    /**
+     * View collection which holds all comment thread children elements.
+     *
+     * These views are:
+     *
+     * * {@link ~CommentThreadView#commentThreadHeaderView `commentThreadHeaderView`} (added at the beginning when the comment thread is
+     * resolved),
+     * * {@link ~CommentThreadView#commentsListView `commentsListView`},
+     * * {@link ~CommentThreadView#commentThreadInputView `commentThreadInputView`}.
+     *
+     * @readonly
+     */
+    readonly commentThreadChildren: ViewCollection;
+    /**
+     * `ConfirmView` uses this element as a container for confirmation dialog.
+     *
+     * The element is set after `view#render()` is called.
+     *
+     * @member {HTMLElement|null} #containerElement
+     */
+    containerElement: HTMLElement | null;
+    /**
+     * Resolve button view. Resolve button fires the 'resolveCommentThread' event when submitted.
+     *
+     * @readonly
+     */
+    readonly resolveButton: ButtonView;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale: Locale, model: CommentThread, localUser: User, config: CommentThreadConfig);
+    /**
+     * Returns a template definition that will be passed to {@link module:ui/view~View#setTemplate}.
+     *
+     * Overwrite this method if you want to set a custom template for the comment thread view.
+     *
+     * The default template looks as follows:
+     *
+     * ```ts
+     * const bind = this.bindTemplate;
+     *
+     * {
+     * 	tag: 'div',
+     *
+     * 	attributes: {
+     * 		class: [
+     * 			'ck-thread',
+     * 			'ck-reset_all-excluded',
+     * 			bind.if( 'isActive', 'ck-thread--active' ),
+     * 			bind.if( 'isUnlinked', 'ck-thread--unlinked' ),
+     * 			bind.if( 'isConfirm', 'ck-thread--remove-confirmation' ),
+     * 			bind.to( 'actionIndicator', value => value ? `ck-thread--${ value }` : '' )
+     * 		],
+     * 		'data-thread-id': this._model.id,
+     * 		// Needed for managing focus after adding new comment.
+     * 		tabindex: -1
+     * 	},
+     *
+     * 	children: [
+     * 		{
+     * 			tag: 'div',
+     * 			attributes: {
+     * 				class: 'ck-thread__container'
+     * 			},
+     * 			children: this.commentThreadChildren
+     * 		}
+     * 	]
+     * };
+     * ```
+     *
+     * See the {@glink features/collaboration/annotations/annotations-custom-view Annotation custom view guide} to learn more about
+     * the possible annotation customizations.
+     *
+     * @returns The definition of a comment thread view's template.
+     */
+    getTemplate(): TemplateDefinition;
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+}
+export {};

package/dist/types/comments/ui/view/commentview.d.ts

@@ -0,0 +1,247 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module comments/comments/ui/view/commentview
+ * @publicApi
+ */
+import { type Locale } from 'ckeditor5/src/utils.js';
+import { ButtonView, type TemplateDefinition, type ViewCollection, type DropdownView } from 'ckeditor5/src/ui.js';
+import { UserView } from 'ckeditor5-collaboration/src/collaboration-core.js';
+import BaseCommentView from './basecommentview.js';
+import type { Comment } from '../../commentsrepository.js';
+import type CommentInputView from './commentinputview.js';
+import type { CommentViewConfig } from '../../../config.js';
+declare const CommentView_base: import("ckeditor5/src/utils.js").Mixed<typeof BaseCommentView, import("@ckeditor/ckeditor5-collaboration-core/src/utils/confirmmixin.js").ConfirmApi>;
+/**
+ * The default view for comment.
+ */
+export default class CommentView extends CommentView_base {
+    locale: Locale;
+    isConfirm: boolean;
+    cancelConfirm: () => void;
+    showConfirm: (key: string, element: unknown) => Promise<void>;
+    /**
+     * A property used by the template.
+     *
+     * It works as a visual indicator for the user that an action is about to be performed.
+     * The value of this property is used in setting the CSS class.
+     * The property is used when the user interacts with the view.
+     *
+     * @observable
+     */
+    actionIndicator: string | null;
+    /**
+     * Comment editor placeholder value.
+     *
+     * @observable
+     */
+    placeholder: string;
+    /**
+     * Comment creation date.
+     *
+     * @observable
+     */
+    authoredAt: Date;
+    /**
+     * Comment resolved date.
+     *
+     * @observable
+     */
+    resolvedAt: Date | null;
+    /**
+     * Collection for UI elements that manage the comment.
+     *
+     * Elements that may be found in the action bar (depending on the comment view properties):
+     *
+     * * the resolve comment thread button (only if the comment is the first comment),
+     * * a dropdown with actions ({@link ~CommentView#dropdown `dropdown`}).
+     */
+    actionBar: ViewCollection;
+    /**
+     * View collection which holds all the comments dropdown elements.
+     *
+     * May include, depending on the view properties:
+     *
+     * * {@link ~CommentView#editButton `editButton`},
+     * * {@link ~CommentView#removeButton `removeButton`}.
+     */
+    items: ViewCollection<ButtonView>;
+    /**
+     * Dropdown containing comment action buttons defined in {@link ~CommentView#items `items`}.
+     */
+    dropdown: DropdownView;
+    /**
+     * Edit button view. Edit button switches the comment to the editing mode.
+     */
+    editButton: ButtonView;
+    /**
+     * Remove button view. Remove button shows a confirmation box that fires the `removeComment` event when submitted.
+     */
+    removeButton: ButtonView;
+    /**
+     * User view for the comment. Presents the comment author.
+     */
+    userView: UserView;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale: Locale, model: Comment, config: CommentViewConfig);
+    /**
+     * Returns a template definition that will be passed to {@link module:ui/view~View#setTemplate}.
+     *
+     * Overwrite this method if you want to set a custom template for the comment view.
+     *
+     * The default template looks as follows:
+     *
+     * ```ts
+     * const bind = this.bindTemplate;
+     *
+     * {
+     * 	tag: 'li',
+     *
+     * 	attributes: {
+     * 		class: [
+     * 			'ck-comment__wrapper',
+     * 			bind.if( 'isConfirm', 'ck-comment--remove-confirmation' )
+     * 		],
+     * 		tabindex: -1
+     * 	},
+     *
+     * 	children: [
+     * 		{
+     * 			tag: 'div',
+     *
+     * 			attributes: {
+     * 				class: [
+     * 					'ck-comment',
+     * 					'ck-annotation',
+     * 					bind.if( 'isSystemComment', 'ck-comment--info' ),
+     * 					bind.if( 'isEditMode', 'ck-comment--edit' ),
+     * 					bind.to( 'actionIndicator', value => value ? `ck-comment--${ value }` : '' )
+     * 				],
+     * 				'data-author-id': this._model.author.id,
+     * 				'data-comment-id': this._model.id
+     * 			},
+     *
+     * 			children: [
+     * 				this.userView,
+     * 				{
+     * 					tag: 'div',
+     *
+     * 					attributes: {
+     * 						class: [ 'ck-comment__main', 'ck-annotation__main' ]
+     * 					},
+     *
+     * 					children: [
+     * 						{
+     * 							tag: 'div',
+     *
+     * 							attributes: {
+     * 								class: [ 'ck-comment__info', 'ck-annotation__info' ]
+     * 							},
+     *
+     * 							children: [
+     * 								{
+     * 									tag: 'span',
+     *
+     * 									children: [
+     * 										{
+     * 											text: this.userView.name
+     * 										}
+     * 									],
+     *
+     * 									attributes: {
+     * 										class: [ 'ck-comment__info-name', 'ck-annotation__info-name' ]
+     * 									}
+     * 								},
+     * 								{
+     * 									tag: 'time',
+     *
+     * 									attributes: {
+     * 										datetime: bind.to( 'authoredAt' ),
+     * 										class: [ 'ck-comment__info-time', 'ck-annotation__info-time' ]
+     * 									},
+     *
+     * 									children: [
+     * 										{
+     * 											text: bind.to( 'authoredAt', value => this._config.formatDateTime( value ) )
+     * 										}
+     * 									]
+     * 								}
+     * 							]
+     * 						},
+     * 						{
+     * 							tag: 'div',
+     *
+     * 							attributes: {
+     * 								class: [
+     * 									'ck-comment__actions',
+     * 									'ck-annotation__actions',
+     * 									bind.if( 'isEditMode', 'ck-comment__actions--hidden' ),
+     * 									bind.if( 'isEditMode', 'ck-annotation__actions--hidden' )
+     * 								]
+     * 							},
+     *
+     * 							children: this.actionBar
+     * 						},
+     * 						{
+     * 							tag: 'div',
+     *
+     * 							attributes: {
+     * 								class: [ 'ck-annotation__content-wrapper' ]
+     * 							},
+     *
+     * 							children: this.visibleView
+     * 						},
+     * 						{
+     * 							tag: 'div',
+     *
+     * 							attributes: {
+     * 								class: [ 'ck-comment__external' ]
+     * 							},
+     *
+     * 							children: [ {
+     * 								text: this.getExternalCommentNote()
+     * 							} ]
+     * 						}
+     * 					]
+     * 				}
+     *
+     * 			]
+     * 		}
+     * 	]
+     * }
+     * ```
+     *
+     * @returns Definition of comment thread view's template.
+     */
+    getTemplate(): TemplateDefinition;
+    /**
+     * @inheritDoc
+     */
+    protected _createCommentInputView(): CommentInputView;
+    /**
+     * Gets the translated note which indicates that the comment comes from an external source.
+     */
+    getExternalCommentNote(): string;
+    /**
+     * Gets the translated notification text which indicates that author name comes from an external source.
+     */
+    getUserViewNotificationText(): string | null;
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+}
+declare module 'ckeditor5/src/ui' {
+    interface DropdownView {
+        isVisible: boolean;
+    }
+}
+export {};

package/dist/types/comments.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module comments/comments
+ * @publicApi
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import CommentsRepository from './comments/commentsrepository.js';
+import CommentsEditing from './comments/commentsediting.js';
+import CommentsUI from './comments/commentsui.js';
+import CommentsOnly from './commentsonly.js';
+import WideSidebar from './annotations/widesidebar.js';
+import NarrowSidebar from './annotations/narrowsidebar.js';
+import InlineAnnotations from './annotations/inlineannotations.js';
+import CommentsArchiveUI from './comments/commentsarchiveui.js';
+import CommentsArchive from './comments/commentsarchive.js';
+/**
+ * The comments plugin, which brings both the UI part and the editing part of this feature.
+ *
+ * It registers {@link module:comments/comments/addcommentthreadcommand~AddCommentThreadCommand the `AddCommentThreadCommand` command}.
+ *
+ * To learn more about the comments feature refer to the {@glink features/collaboration/comments/comments Comments} guide.
+ */
+export default class Comments extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof CommentsRepository, typeof CommentsEditing, typeof CommentsUI, typeof CommentsArchive, typeof CommentsArchiveUI, typeof CommentsOnly, typeof WideSidebar, typeof NarrowSidebar, typeof InlineAnnotations];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "Comments";
+}

package/dist/types/commentsonly.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module comments/commentsonly
+ * @publicApi
+ */
+import { Plugin, type Editor } from 'ckeditor5/src/core.js';
+import CommentsEditing from './comments/commentsediting.js';
+/**
+ * The `CommentsOnly` plugin allows you to put the editor in a mode where a user can only add, edit or delete comments.
+ *
+ * Check the {@glink features/collaboration/comments/comments-only-mode Comments-only mode} guide to learn how to use this plugin.
+ */
+export default class CommentsOnly extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "CommentsOnly";
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof CommentsEditing];
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    afterInit(): void;
+}