@ckeditor/ckeditor5-comments 48.8.1-alpha.4 → 49.0.0-alpha.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (199) hide show
  1. package/LICENSE.md +1 -1
  2. package/dist/annotations/annotation.d.ts +84 -87
  3. package/dist/annotations/annotationcollection.d.ts +83 -83
  4. package/dist/annotations/annotations.d.ts +148 -148
  5. package/dist/annotations/annotationsuis.d.ts +235 -235
  6. package/dist/annotations/editorannotations.d.ts +71 -71
  7. package/dist/annotations/inlineannotations.d.ts +92 -93
  8. package/dist/annotations/narrowsidebar.d.ts +87 -88
  9. package/dist/annotations/sidebar.d.ts +105 -105
  10. package/dist/annotations/view/annotationcounterbuttonview.d.ts +24 -24
  11. package/dist/annotations/view/annotationview.d.ts +82 -83
  12. package/dist/annotations/view/sidebaritemview.d.ts +54 -54
  13. package/dist/annotations/view/sidebarview.d.ts +47 -48
  14. package/dist/annotations/widesidebar.d.ts +80 -80
  15. package/dist/augmentation.d.ts +57 -57
  16. package/dist/comments/addcommentthreadcommand.d.ts +69 -69
  17. package/dist/comments/commentsarchive.d.ts +34 -34
  18. package/dist/comments/commentsarchiveui.d.ts +47 -48
  19. package/dist/comments/commentsediting.d.ts +89 -90
  20. package/dist/comments/commentsrepository.d.ts +1039 -1054
  21. package/dist/comments/commentsui.d.ts +40 -40
  22. package/dist/comments/integrations/clipboard.d.ts +21 -21
  23. package/dist/comments/integrations/commentsrestrictededitingmode.d.ts +12 -12
  24. package/dist/comments/integrations/importword.d.ts +16 -16
  25. package/dist/comments/integrations/showcommenthighlights.d.ts +14 -14
  26. package/dist/comments/ui/commenteditor/commenteditor.d.ts +33 -32
  27. package/dist/comments/ui/commenteditor/commenteditorui.d.ts +27 -27
  28. package/dist/comments/ui/commenteditor/commenteditoruiview.d.ts +32 -32
  29. package/dist/comments/ui/commentthreadcontroller.d.ts +62 -60
  30. package/dist/comments/ui/view/basecommentthreadview.d.ts +134 -134
  31. package/dist/comments/ui/view/basecommentview.d.ts +136 -136
  32. package/dist/comments/ui/view/collapsedcommentsview.d.ts +16 -9
  33. package/dist/comments/ui/view/commentcontentview.d.ts +10 -10
  34. package/dist/comments/ui/view/commentinputview.d.ts +93 -93
  35. package/dist/comments/ui/view/commentsarchiveview.d.ts +41 -41
  36. package/dist/comments/ui/view/commentslistview.d.ts +114 -107
  37. package/dist/comments/ui/view/commentthreadheadercontextview.d.ts +19 -19
  38. package/dist/comments/ui/view/commentthreadheaderview.d.ts +67 -67
  39. package/dist/comments/ui/view/commentthreadinputview.d.ts +51 -51
  40. package/dist/comments/ui/view/commentthreadview.d.ts +116 -116
  41. package/dist/comments/ui/view/commentview.d.ts +225 -230
  42. package/dist/comments.d.ts +38 -38
  43. package/dist/commentsonly.d.ts +36 -36
  44. package/dist/config.d.ts +200 -185
  45. package/dist/index-content.css +22 -22
  46. package/dist/index-editor.css +600 -556
  47. package/dist/index.css +439 -391
  48. package/dist/index.d.ts +37 -35
  49. package/dist/index.js +11 -11
  50. package/dist/translations/af.js +1 -1
  51. package/dist/translations/af.umd.js +1 -1
  52. package/dist/translations/ar.js +1 -1
  53. package/dist/translations/ar.umd.js +1 -1
  54. package/dist/translations/ast.js +1 -1
  55. package/dist/translations/ast.umd.js +1 -1
  56. package/dist/translations/az.js +1 -1
  57. package/dist/translations/az.umd.js +1 -1
  58. package/dist/translations/be.js +1 -1
  59. package/dist/translations/be.umd.js +1 -1
  60. package/dist/translations/bg.js +1 -1
  61. package/dist/translations/bg.umd.js +1 -1
  62. package/dist/translations/bn.js +1 -1
  63. package/dist/translations/bn.umd.js +1 -1
  64. package/dist/translations/bs.js +1 -1
  65. package/dist/translations/bs.umd.js +1 -1
  66. package/dist/translations/ca.js +1 -1
  67. package/dist/translations/ca.umd.js +1 -1
  68. package/dist/translations/cs.js +1 -1
  69. package/dist/translations/cs.umd.js +1 -1
  70. package/dist/translations/da.js +1 -1
  71. package/dist/translations/da.umd.js +1 -1
  72. package/dist/translations/de-ch.js +1 -1
  73. package/dist/translations/de-ch.umd.js +1 -1
  74. package/dist/translations/de.js +1 -1
  75. package/dist/translations/de.umd.js +1 -1
  76. package/dist/translations/el.js +1 -1
  77. package/dist/translations/el.umd.js +1 -1
  78. package/dist/translations/en-au.js +1 -1
  79. package/dist/translations/en-au.umd.js +1 -1
  80. package/dist/translations/en-gb.js +1 -1
  81. package/dist/translations/en-gb.umd.js +1 -1
  82. package/dist/translations/en.js +1 -1
  83. package/dist/translations/en.umd.js +1 -1
  84. package/dist/translations/eo.js +1 -1
  85. package/dist/translations/eo.umd.js +1 -1
  86. package/dist/translations/es-co.js +1 -1
  87. package/dist/translations/es-co.umd.js +1 -1
  88. package/dist/translations/es.js +1 -1
  89. package/dist/translations/es.umd.js +1 -1
  90. package/dist/translations/et.js +1 -1
  91. package/dist/translations/et.umd.js +1 -1
  92. package/dist/translations/eu.js +1 -1
  93. package/dist/translations/eu.umd.js +1 -1
  94. package/dist/translations/fa.js +1 -1
  95. package/dist/translations/fa.umd.js +1 -1
  96. package/dist/translations/fi.js +1 -1
  97. package/dist/translations/fi.umd.js +1 -1
  98. package/dist/translations/fr.js +1 -1
  99. package/dist/translations/fr.umd.js +1 -1
  100. package/dist/translations/gl.js +1 -1
  101. package/dist/translations/gl.umd.js +1 -1
  102. package/dist/translations/gu.js +1 -1
  103. package/dist/translations/gu.umd.js +1 -1
  104. package/dist/translations/he.js +1 -1
  105. package/dist/translations/he.umd.js +1 -1
  106. package/dist/translations/hi.js +1 -1
  107. package/dist/translations/hi.umd.js +1 -1
  108. package/dist/translations/hr.js +1 -1
  109. package/dist/translations/hr.umd.js +1 -1
  110. package/dist/translations/hu.js +1 -1
  111. package/dist/translations/hu.umd.js +1 -1
  112. package/dist/translations/hy.js +1 -1
  113. package/dist/translations/hy.umd.js +1 -1
  114. package/dist/translations/id.js +1 -1
  115. package/dist/translations/id.umd.js +1 -1
  116. package/dist/translations/it.js +1 -1
  117. package/dist/translations/it.umd.js +1 -1
  118. package/dist/translations/ja.js +1 -1
  119. package/dist/translations/ja.umd.js +1 -1
  120. package/dist/translations/jv.js +1 -1
  121. package/dist/translations/jv.umd.js +1 -1
  122. package/dist/translations/kk.js +1 -1
  123. package/dist/translations/kk.umd.js +1 -1
  124. package/dist/translations/km.js +1 -1
  125. package/dist/translations/km.umd.js +1 -1
  126. package/dist/translations/kn.js +1 -1
  127. package/dist/translations/kn.umd.js +1 -1
  128. package/dist/translations/ko.js +1 -1
  129. package/dist/translations/ko.umd.js +1 -1
  130. package/dist/translations/ku.js +1 -1
  131. package/dist/translations/ku.umd.js +1 -1
  132. package/dist/translations/lt.js +1 -1
  133. package/dist/translations/lt.umd.js +1 -1
  134. package/dist/translations/lv.js +1 -1
  135. package/dist/translations/lv.umd.js +1 -1
  136. package/dist/translations/ms.js +1 -1
  137. package/dist/translations/ms.umd.js +1 -1
  138. package/dist/translations/nb.js +1 -1
  139. package/dist/translations/nb.umd.js +1 -1
  140. package/dist/translations/ne.js +1 -1
  141. package/dist/translations/ne.umd.js +1 -1
  142. package/dist/translations/nl.js +1 -1
  143. package/dist/translations/nl.umd.js +1 -1
  144. package/dist/translations/no.js +1 -1
  145. package/dist/translations/no.umd.js +1 -1
  146. package/dist/translations/oc.js +1 -1
  147. package/dist/translations/oc.umd.js +1 -1
  148. package/dist/translations/pl.js +1 -1
  149. package/dist/translations/pl.umd.js +1 -1
  150. package/dist/translations/pt-br.js +1 -1
  151. package/dist/translations/pt-br.umd.js +1 -1
  152. package/dist/translations/pt.js +1 -1
  153. package/dist/translations/pt.umd.js +1 -1
  154. package/dist/translations/ro.js +1 -1
  155. package/dist/translations/ro.umd.js +1 -1
  156. package/dist/translations/ru.js +1 -1
  157. package/dist/translations/ru.umd.js +1 -1
  158. package/dist/translations/si.js +1 -1
  159. package/dist/translations/si.umd.js +1 -1
  160. package/dist/translations/sk.js +1 -1
  161. package/dist/translations/sk.umd.js +1 -1
  162. package/dist/translations/sl.js +1 -1
  163. package/dist/translations/sl.umd.js +1 -1
  164. package/dist/translations/sq.js +1 -1
  165. package/dist/translations/sq.umd.js +1 -1
  166. package/dist/translations/sr-latn.js +1 -1
  167. package/dist/translations/sr-latn.umd.js +1 -1
  168. package/dist/translations/sr.js +1 -1
  169. package/dist/translations/sr.umd.js +1 -1
  170. package/dist/translations/sv.js +1 -1
  171. package/dist/translations/sv.umd.js +1 -1
  172. package/dist/translations/th.js +1 -1
  173. package/dist/translations/th.umd.js +1 -1
  174. package/dist/translations/ti.js +1 -1
  175. package/dist/translations/ti.umd.js +1 -1
  176. package/dist/translations/tk.js +1 -1
  177. package/dist/translations/tk.umd.js +1 -1
  178. package/dist/translations/tr.js +1 -1
  179. package/dist/translations/tr.umd.js +1 -1
  180. package/dist/translations/tt.js +1 -1
  181. package/dist/translations/tt.umd.js +1 -1
  182. package/dist/translations/ug.js +1 -1
  183. package/dist/translations/ug.umd.js +1 -1
  184. package/dist/translations/uk.js +1 -1
  185. package/dist/translations/uk.umd.js +1 -1
  186. package/dist/translations/ur.js +1 -1
  187. package/dist/translations/ur.umd.js +1 -1
  188. package/dist/translations/uz.js +1 -1
  189. package/dist/translations/uz.umd.js +1 -1
  190. package/dist/translations/vi.js +1 -1
  191. package/dist/translations/vi.umd.js +1 -1
  192. package/dist/translations/zh-cn.js +1 -1
  193. package/dist/translations/zh-cn.umd.js +1 -1
  194. package/dist/translations/zh.js +1 -1
  195. package/dist/translations/zh.umd.js +1 -1
  196. package/dist/utils/common-translations.d.ts +6 -6
  197. package/dist/utils/createmutationobserver.d.ts +9 -9
  198. package/dist/utils/splitmarkername.d.ts +10 -10
  199. package/package.json +17 -17
@@ -1,1123 +1,1108 @@
1
1
  /**
2
- * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
3
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
4
- */
2
+ * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
3
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
4
+ */
5
5
  /**
6
- * @module comments/comments/commentsrepository
7
- * @publicApi
8
- */
9
- import { PendingActions, ContextPlugin, Editor, type Context } from '@ckeditor/ckeditor5-core';
10
- import { Collection } from '@ckeditor/ckeditor5-utils';
11
- import { Users, type User } from '@ckeditor/ckeditor5-collaboration-core';
12
- import { CommentThreadController } from './ui/commentthreadcontroller.js';
13
- import '../../theme/comment.css';
14
- import '../../theme/commentthread.css';
15
- import '../../theme/commentinput.css';
16
- import { Annotation, type AnnotationTarget } from '../annotations/annotation.js';
17
- import { Annotations } from '../annotations/annotations.js';
18
- import type { BaseCommentThreadView } from './ui/view/basecommentthreadview.js';
6
+ * @module comments/comments/commentsrepository
7
+ * @publicApi
8
+ */
9
+ import { PendingActions, ContextPlugin, Editor, type Context, type PluginDependenciesOf } from "@ckeditor/ckeditor5-core";
10
+ import { Collection, type ObservableMixinConstructor } from "@ckeditor/ckeditor5-utils";
11
+ import { Users, type User } from "@ckeditor/ckeditor5-collaboration-core";
12
+ import { CommentThreadController } from "./ui/commentthreadcontroller.js";
13
+ import { Annotation, type AnnotationTarget } from "../annotations/annotation.js";
14
+ import { Annotations } from "../annotations/annotations.js";
15
+ import type { BaseCommentThreadView } from "./ui/view/basecommentthreadview.js";
16
+ declare const _CommentThreadBase: ObservableMixinConstructor;
17
+ declare const _CommentBase: ObservableMixinConstructor;
19
18
  /**
20
- * Stores the list of {@link module:comments/comments/commentsrepository~CommentThread}
21
- * and provides event-driven API for managing them. It is also responsible for using the comments adapter
22
- * to communicate with the data source.
23
- *
24
- * {@link module:comments/comments/commentsrepository~CommentsRepository} is a context plugin.
25
- * It can be added to a context or to an editor. Add it to the context configuration if you use
26
- * {@link module:core/context~Context} in your integration.
27
- *
28
- * The event-driven API makes it possible to attach a listener to each action that changes comment data.
29
- * Using different event priorities allows to attach an action before the main action ('low' priority)
30
- * or after the main action ('high' priority). It works very similar to
31
- * {@link module:utils/observablemixin~Observable#decorate}.
32
- *
33
- * Sample usage:
34
- *
35
- * ```ts
36
- * // Get the comments repository:
37
- * const commentsRepository = editor.plugins.get( 'CommentsRepository' );
38
- *
39
- * // Create a new, empty comment thread on a DOM form field element:
40
- * commentsRepository.openNewCommentThread( { channelId, target: formFieldElement } );
41
- *
42
- * // Get all comment threads:
43
- * commentsRepository.getCommentThreads();
44
- *
45
- * // Set the adapter:
46
- * commentsRepository.adapter = {
47
- * // ...
48
- * };
49
- * ```
50
- *
51
- * For more information about the comments adapter see {@link module:comments/comments/commentsrepository~CommentsAdapter}.
52
- */
19
+ * Stores the list of {@link module:comments/comments/commentsrepository~CommentThread}
20
+ * and provides event-driven API for managing them. It is also responsible for using the comments adapter
21
+ * to communicate with the data source.
22
+ *
23
+ * {@link module:comments/comments/commentsrepository~CommentsRepository} is a context plugin.
24
+ * It can be added to a context or to an editor. Add it to the context configuration if you use
25
+ * {@link module:core/context~Context} in your integration.
26
+ *
27
+ * The event-driven API makes it possible to attach a listener to each action that changes comment data.
28
+ * Using different event priorities allows to attach an action before the main action ('low' priority)
29
+ * or after the main action ('high' priority). It works very similar to
30
+ * {@link module:utils/observablemixin~Observable#decorate}.
31
+ *
32
+ * Sample usage:
33
+ *
34
+ * ```ts
35
+ * // Get the comments repository:
36
+ * const commentsRepository = editor.plugins.get( 'CommentsRepository' );
37
+ *
38
+ * // Create a new, empty comment thread on a DOM form field element:
39
+ * commentsRepository.openNewCommentThread( { channelId, target: formFieldElement } );
40
+ *
41
+ * // Get all comment threads:
42
+ * commentsRepository.getCommentThreads();
43
+ *
44
+ * // Set the adapter:
45
+ * commentsRepository.adapter = {
46
+ * // ...
47
+ * };
48
+ * ```
49
+ *
50
+ * For more information about the comments adapter see {@link module:comments/comments/commentsrepository~CommentsAdapter}.
51
+ */
53
52
  export declare class CommentsRepository extends ContextPlugin {
54
- /**
55
- * The currently active comment thread.
56
- * An annotation with this thread will be marked as active.
57
- *
58
- * @observable
59
- */
60
- activeCommentThread: CommentThread | null;
61
- /**
62
- * @inheritDoc
63
- */
64
- static get requires(): readonly [typeof Annotations, typeof PendingActions, typeof Users];
65
- /**
66
- * @inheritDoc
67
- */
68
- static get pluginName(): "CommentsRepository";
69
- /**
70
- * @inheritDoc
71
- */
72
- static get isOfficialPlugin(): true;
73
- /**
74
- * @inheritDoc
75
- */
76
- static get isPremiumPlugin(): true;
77
- /**
78
- * @inheritDoc
79
- */
80
- constructor(context: Context | Editor);
81
- /**
82
- * @inheritDoc
83
- */
84
- init(): void;
85
- /**
86
- * An adapter object that should communicate with the data source to fetch or save the comments data.
87
- */
88
- set adapter(adapter: CommentsAdapter);
89
- get adapter(): CommentsAdapter;
90
- /**
91
- * Adds a new comment thread.
92
- *
93
- * When a target is provided, the comment annotation will be attached to this target.
94
- *
95
- * Use this method to load the comments data during the editor initialization
96
- * if you do not use the adapter integration.
97
- *
98
- * **Note:** This method fires the {@link #event:addCommentThread} event and the default behavior
99
- * is added as a `'normal'` priority listener. It makes it possible to cancel the method
100
- * or call some custom code before or after the default behavior is executed.
101
- *
102
- * **Note:** The comments adapter will send the data only if `commentThreadData.comments`
103
- * is not empty and `commentThreadData.isFromAdapter` is set to `false`.
104
- *
105
- * See also `CommentsRepository#openNewCommentThread()`.
106
- *
107
- * An example of loading a comment thread on editor initialization:
108
- *
109
- * ```ts
110
- * commentsRepository.addCommentThread( {
111
- * threadId: 'thread-id',
112
- * channelId: 'channel-id',
113
- * comments: [
114
- * {
115
- * commentId: 'comment-1', // String
116
- * authorId: 'author-id', // String
117
- * content: 'First comment', // String
118
- * createdAt: new Date( ... ) // Date instance
119
- * },
120
- * // ...
121
- * ],
122
- * target: () => ...,
123
- * // Added during initialization, so do not call the adapter:
124
- * isFromAdapter: true
125
- * } );
126
- * ```
127
- *
128
- * See also {@link module:comments/comments/commentsrepository~CommentThread#setAttribute} and
129
- * {@link module:comments/comments/commentsrepository~CommentThread#removeAttribute}.
130
- *
131
- * @fires addCommentThread
132
- * @param data The data of the comment thread to add.
133
- * @param data.channelId The ID of a document or context to which the comment thread is added.
134
- * @param data.threadId The ID of the added comment thread.
135
- * @param data.comments Comments in the comment thread. See the example above.
136
- * @param data.unlinkedAt The date when the content related to the comment thread was lost (usually, the commented content was
137
- * removed from the document).
138
- * @param data.resolvedAt The date when the comment thread has been resolved.
139
- * @param data.resolvedBy The ID of user who resolved the comment thread.
140
- * @param data.target The target that the comment
141
- * balloon should be attached to. If a function is passed, it should return a DOM element or `Rect`.
142
- * @param data.context The text on which the comment thread was created on or similar contextual information for the comment thread.
143
- * To be displayed as an additional hint for archived comment threads.
144
- * @param data.attributes Custom comment attributes.
145
- * @param data.isResolvable Indicates whether the comment thread can become resolved.
146
- * Set this flag to `false` to disable the possibility of resolving given comment thread.
147
- * @param data.isSubmitted Indicates whether the comment thread has been submitted.
148
- * Comment thread is submitted after adding the first comment, however, in some cases,
149
- * it could be necessary to manage it in a custom way (e.g. track changes).
150
- * @param data.isFromAdapter A flag describing whether the added data
151
- * comes from an adapter (`true`) or is a new data (`false`). If set to `true`, the
152
- * comment data will be added only in the editor and will not be sent to the adapter.
153
- * @returns The added comment thread.
154
- */
155
- addCommentThread({ channelId, threadId, comments, unlinkedAt, resolvedAt, resolvedBy, target, context, attributes, isResolvable, isSubmitted, isFromAdapter }?: Partial<AddCommentThreadEventData>): CommentThread | undefined;
156
- /**
157
- * Creates a new, empty comment thread.
158
- *
159
- * Displays a new comment annotation attached to the target and focuses the comment editor.
160
- * When the comment data is submitted, the comment thread is added to the editor
161
- * and sent to the adapter.
162
- *
163
- * Use this method to start a new comment thread after a user performed an action
164
- * (clicked a button, etc.).
165
- *
166
- * @param commentThreadData The data of the comment thread to add.
167
- * @returns The created comment thread or `null` if there was a problem
168
- * creating the thread (for example, if the comments repository was in the read-only mode).
169
- * @fires addCommentThread
170
- */
171
- openNewCommentThread({ channelId, threadId, target, context, isResolvable }: AddCommentThreadEventData): CommentThread | null;
172
- /**
173
- * Checks if a comment thread with a given ID is added to the repository.
174
- */
175
- hasCommentThread(threadId: string): boolean;
176
- /**
177
- * Updates an existing comment thread. See also
178
- * {@link module:comments/comments/commentsrepository~CommentThread#setAttribute} and
179
- * {@link module:comments/comments/commentsrepository~CommentThread#removeAttribute}.
180
- *
181
- * @param data The data of the comment thread to add.
182
- * @returns The updated comment thread.
183
- * @fires updateCommentThread
184
- */
185
- updateCommentThread({ channelId, threadId, context, unlinkedAt, attributes, isFromAdapter }: UpdateCommentThreadEventData): CommentThread;
186
- /**
187
- * Returns comment thread of given id.
188
- */
189
- getCommentThread(threadId: string): CommentThread | undefined;
190
- /**
191
- * Gets the comment thread data using the adapter and adds the thread to the editor.
192
- *
193
- * When the comment thread is already present in the repository,
194
- * then the adapter will not be used but the result will be asynchronous as well.
195
- */
196
- fetchCommentThread({ channelId, threadId }?: BaseCommentThread): Promise<CommentThread | undefined>;
197
- getCommentThreads(data?: {
198
- channelId?: string | symbol;
199
- skipNotAttached?: boolean;
200
- skipEmpty?: boolean;
201
- toJSON?: false;
202
- }): Array<CommentThread>;
203
- getCommentThreads(data: {
204
- channelId?: string | symbol;
205
- skipNotAttached?: boolean;
206
- skipEmpty?: boolean;
207
- toJSON: true;
208
- }): Array<CommentThreadDataJSON>;
209
- /**
210
- * Returns the annotation associated with the given comment thread.
211
- */
212
- getAnnotationForCommentThread(thread: CommentThread): Annotation | null;
213
- /**
214
- * Returns the comment thread associated with the given annotation.
215
- */
216
- getCommentThreadForAnnotation(annotation: Annotation): CommentThread | null;
217
- /**
218
- * Marks a comment thread with the given ID as active.
219
- * When `threadId` is `null`, the currently active comment thread will be deactivated.
220
- */
221
- setActiveCommentThread(threadId: string | null): void;
222
- /**
223
- * Changes the read-only state for comment threads.
224
- *
225
- * When the value is `true` then all comment threads will be switched to read-only,
226
- * when the value is `false` then all comment threads will be switched to editing mode.
227
- *
228
- * Optionally new state can be applied to a comment threads limited to a given channel.
229
- * This function has precedence over any permission settings.
230
- */
231
- switchReadOnly(value: boolean, channelId?: string | symbol): void;
232
- /**
233
- * Returns `true` if a given channel is set to read-only mode, returns `false` otherwise.
234
- */
235
- isReadOnly(channelId: string | symbol): boolean;
236
- /**
237
- * Create an instance of the {@link module:comments/comments/ui/commentthreadcontroller~CommentThreadController} class.
238
- *
239
- * @param commentThreadModel Comment thread model.
240
- * @param commentThreadView Comment thread view.
241
- */
242
- createCommentThreadController(commentThreadModel: CommentThread, commentThreadView: BaseCommentThreadView): CommentThreadController;
243
- /**
244
- * Gets permissions set for repository (or default if permissions was not set).
245
- */
246
- getPermissions(channelId?: string | symbol): CommentPermissionsConfig;
53
+ /**
54
+ * The currently active comment thread.
55
+ * An annotation with this thread will be marked as active.
56
+ *
57
+ * @observable
58
+ */
59
+ activeCommentThread: CommentThread | null;
60
+ /**
61
+ * @inheritDoc
62
+ */
63
+ static get requires(): PluginDependenciesOf<[Annotations, PendingActions, Users]>;
64
+ /**
65
+ * @inheritDoc
66
+ */
67
+ static get pluginName(): "CommentsRepository";
68
+ /**
69
+ * @inheritDoc
70
+ */
71
+ static override get isOfficialPlugin(): true;
72
+ /**
73
+ * @inheritDoc
74
+ */
75
+ static override get isPremiumPlugin(): true;
76
+ /**
77
+ * @inheritDoc
78
+ */
79
+ constructor(context: Context | Editor);
80
+ /**
81
+ * @inheritDoc
82
+ */
83
+ init(): void;
84
+ /**
85
+ * An adapter object that should communicate with the data source to fetch or save the comments data.
86
+ */
87
+ set adapter(adapter: CommentsAdapter);
88
+ get adapter(): CommentsAdapter;
89
+ /**
90
+ * Adds a new comment thread.
91
+ *
92
+ * When a target is provided, the comment annotation will be attached to this target.
93
+ *
94
+ * Use this method to load the comments data during the editor initialization
95
+ * if you do not use the adapter integration.
96
+ *
97
+ * **Note:** This method fires the {@link #event:addCommentThread} event and the default behavior
98
+ * is added as a `'normal'` priority listener. It makes it possible to cancel the method
99
+ * or call some custom code before or after the default behavior is executed.
100
+ *
101
+ * **Note:** The comments adapter will send the data only if `commentThreadData.comments`
102
+ * is not empty and `commentThreadData.isFromAdapter` is set to `false`.
103
+ *
104
+ * See also `CommentsRepository#openNewCommentThread()`.
105
+ *
106
+ * An example of loading a comment thread on editor initialization:
107
+ *
108
+ * ```ts
109
+ * commentsRepository.addCommentThread( {
110
+ * threadId: 'thread-id',
111
+ * channelId: 'channel-id',
112
+ * comments: [
113
+ * {
114
+ * commentId: 'comment-1', // String
115
+ * authorId: 'author-id', // String
116
+ * content: 'First comment', // String
117
+ * createdAt: new Date( ... ) // Date instance
118
+ * },
119
+ * // ...
120
+ * ],
121
+ * target: () => ...,
122
+ * // Added during initialization, so do not call the adapter:
123
+ * isFromAdapter: true
124
+ * } );
125
+ * ```
126
+ *
127
+ * See also {@link module:comments/comments/commentsrepository~CommentThread#setAttribute} and
128
+ * {@link module:comments/comments/commentsrepository~CommentThread#removeAttribute}.
129
+ *
130
+ * @fires addCommentThread
131
+ * @param data The data of the comment thread to add.
132
+ * @param data.channelId The ID of a document or context to which the comment thread is added.
133
+ * @param data.threadId The ID of the added comment thread.
134
+ * @param data.comments Comments in the comment thread. See the example above.
135
+ * @param data.unlinkedAt The date when the content related to the comment thread was lost (usually, the commented content was
136
+ * removed from the document).
137
+ * @param data.resolvedAt The date when the comment thread has been resolved.
138
+ * @param data.resolvedBy The ID of user who resolved the comment thread.
139
+ * @param data.target The target that the comment
140
+ * balloon should be attached to. If a function is passed, it should return a DOM element or `Rect`.
141
+ * @param data.context The text on which the comment thread was created on or similar contextual information for the comment thread.
142
+ * To be displayed as an additional hint for archived comment threads.
143
+ * @param data.attributes Custom comment attributes.
144
+ * @param data.isResolvable Indicates whether the comment thread can become resolved.
145
+ * Set this flag to `false` to disable the possibility of resolving given comment thread.
146
+ * @param data.isSubmitted Indicates whether the comment thread has been submitted.
147
+ * Comment thread is submitted after adding the first comment, however, in some cases,
148
+ * it could be necessary to manage it in a custom way (e.g. track changes).
149
+ * @param data.isFromAdapter A flag describing whether the added data
150
+ * comes from an adapter (`true`) or is a new data (`false`). If set to `true`, the
151
+ * comment data will be added only in the editor and will not be sent to the adapter.
152
+ * @returns The added comment thread.
153
+ */
154
+ addCommentThread({ channelId, threadId, comments, unlinkedAt, resolvedAt, resolvedBy, target, context, attributes, isResolvable, isSubmitted, isFromAdapter }?: Partial<Omit<AddCommentThreadEventData, "target">> & {
155
+ target?: AnnotationTarget | null;
156
+ }): CommentThread | undefined;
157
+ /**
158
+ * Creates a new, empty comment thread.
159
+ *
160
+ * Displays a new comment annotation attached to the target and focuses the comment editor.
161
+ * When the comment data is submitted, the comment thread is added to the editor
162
+ * and sent to the adapter.
163
+ *
164
+ * Use this method to start a new comment thread after a user performed an action
165
+ * (clicked a button, etc.).
166
+ *
167
+ * @param commentThreadData The data of the comment thread to add.
168
+ * @returns The created comment thread or `null` if there was a problem
169
+ * creating the thread (for example, if the comments repository was in the read-only mode).
170
+ * @fires addCommentThread
171
+ */
172
+ openNewCommentThread({ channelId, threadId, target, context, isResolvable }: AddCommentThreadEventData): CommentThread | null;
173
+ /**
174
+ * Checks if a comment thread with a given ID is added to the repository.
175
+ */
176
+ hasCommentThread(threadId: string): boolean;
177
+ /**
178
+ * Updates an existing comment thread. See also
179
+ * {@link module:comments/comments/commentsrepository~CommentThread#setAttribute} and
180
+ * {@link module:comments/comments/commentsrepository~CommentThread#removeAttribute}.
181
+ *
182
+ * @param data The data of the comment thread to add.
183
+ * @returns The updated comment thread.
184
+ * @fires updateCommentThread
185
+ */
186
+ updateCommentThread({ channelId, threadId, context, unlinkedAt, attributes, isFromAdapter }: UpdateCommentThreadEventData): CommentThread;
187
+ /**
188
+ * Returns comment thread of given id.
189
+ */
190
+ getCommentThread(threadId: string): CommentThread | undefined;
191
+ /**
192
+ * Gets the comment thread data using the adapter and adds the thread to the editor.
193
+ *
194
+ * When the comment thread is already present in the repository,
195
+ * then the adapter will not be used but the result will be asynchronous as well.
196
+ */
197
+ fetchCommentThread({ channelId, threadId }?: BaseCommentThread): Promise<CommentThread | undefined>;
198
+ getCommentThreads(data?: {
199
+ channelId?: string | symbol;
200
+ skipNotAttached?: boolean;
201
+ skipEmpty?: boolean;
202
+ toJSON?: false;
203
+ }): Array<CommentThread>;
204
+ getCommentThreads(data: {
205
+ channelId?: string | symbol;
206
+ skipNotAttached?: boolean;
207
+ skipEmpty?: boolean;
208
+ toJSON: true;
209
+ }): Array<CommentThreadDataJSON>;
210
+ /**
211
+ * Returns the annotation associated with the given comment thread.
212
+ */
213
+ getAnnotationForCommentThread(thread: CommentThread): Annotation | null;
214
+ /**
215
+ * Returns the comment thread associated with the given annotation.
216
+ */
217
+ getCommentThreadForAnnotation(annotation: Annotation): CommentThread | null;
218
+ /**
219
+ * Marks a comment thread with the given ID as active.
220
+ * When `threadId` is `null`, the currently active comment thread will be deactivated.
221
+ */
222
+ setActiveCommentThread(threadId: string | null): void;
223
+ /**
224
+ * Changes the read-only state for comment threads.
225
+ *
226
+ * When the value is `true` then all comment threads will be switched to read-only,
227
+ * when the value is `false` then all comment threads will be switched to editing mode.
228
+ *
229
+ * Optionally new state can be applied to a comment threads limited to a given channel.
230
+ * This function has precedence over any permission settings.
231
+ */
232
+ switchReadOnly(value: boolean, channelId?: string | symbol): void;
233
+ /**
234
+ * Returns `true` if a given channel is set to read-only mode, returns `false` otherwise.
235
+ */
236
+ isReadOnly(channelId: string | symbol): boolean;
237
+ /**
238
+ * Create an instance of the {@link module:comments/comments/ui/commentthreadcontroller~CommentThreadController} class.
239
+ *
240
+ * @param commentThreadModel Comment thread model.
241
+ * @param commentThreadView Comment thread view.
242
+ */
243
+ createCommentThreadController(commentThreadModel: CommentThread, commentThreadView: BaseCommentThreadView): CommentThreadController;
244
+ /**
245
+ * Gets permissions set for repository (or default if permissions was not set).
246
+ */
247
+ getPermissions(channelId?: string | symbol): CommentPermissionsConfig;
247
248
  }
248
249
  export interface CommentPermissionsConfig {
249
- /**
250
- * Allows for removing other users' threads.
251
- */
252
- admin: boolean;
253
- /**
254
- * Allows for editing and removing any comments created by other users.
255
- */
256
- modifyAll: boolean;
257
- /**
258
- * Allows for adding new comments as well as editing and removing comments created by this user.
259
- */
260
- write: boolean;
261
- /**
262
- * Allows for resolving and reopening comment threads.
263
- */
264
- resolve: boolean;
250
+ /**
251
+ * Allows for removing other users' threads.
252
+ */
253
+ admin: boolean;
254
+ /**
255
+ * Allows for editing and removing any comments created by other users.
256
+ */
257
+ modifyAll: boolean;
258
+ /**
259
+ * Allows for adding new comments as well as editing and removing comments created by this user.
260
+ */
261
+ write: boolean;
262
+ /**
263
+ * Allows for resolving and reopening comment threads.
264
+ */
265
+ resolve: boolean;
265
266
  }
266
- declare const CommentThread_base: {
267
- new (): import("@ckeditor/ckeditor5-utils").Observable;
268
- prototype: import("@ckeditor/ckeditor5-utils").Observable;
269
- };
270
267
  /**
271
- * Comment thread representation.
272
- * Stores a list of {@link module:comments/comments/commentsrepository~Comment `Comments`}.
273
- */
274
- export declare class CommentThread extends /* #__PURE__ -- @preserve */ CommentThread_base {
275
- /**
276
- * Informs if the comment thread is in read-only state (`true`) or not (`false`).
277
- *
278
- * @observable
279
- */
280
- isReadOnly: boolean;
281
- /**
282
- * Informs if the comment thread can be removed by the local user.
283
- *
284
- * @observable
285
- */
286
- isRemovable: boolean;
287
- /**
288
- * Informs if a user has permission to add a new comment to the comment thread.
289
- *
290
- * @observable
291
- */
292
- canComment: boolean;
293
- /**
294
- * Date when the comment thread has been archived.
295
- *
296
- * Comment threads become archived after they are {@link #resolvedAt resolved} or {@link #unlinkedAt unlinked}.
297
- * If the comment thread is resolved and/or unlinked, this value is set to the earliest of the dates. Otherwise, it is `null`.
298
- *
299
- * @observable
300
- */
301
- archivedAt: Date | null;
302
- /**
303
- * The date when the content related to the comment thread was lost (usually, the commented content was removed from the document).
304
- *
305
- * @observable
306
- */
307
- unlinkedAt: Date | null;
308
- /**
309
- * User id which resolved the comment thread.
310
- *
311
- * @observable
312
- */
313
- resolvedBy: User | null;
314
- /**
315
- * Date when the comment thread has been resolved.
316
- *
317
- * @observable
318
- */
319
- resolvedAt: Date | null;
320
- /**
321
- * Informs if the comment thread is resolved.
322
- *
323
- * @observable
324
- */
325
- readonly isResolved: boolean;
326
- /**
327
- * Custom comment thread attributes. See also {@link #setAttribute} and {@link #removeAttribute}.
328
- *
329
- * @observable
330
- */
331
- attributes: Record<string, unknown>;
332
- /**
333
- * The channel where the comment thread was created.
334
- */
335
- channelId: string | symbol;
336
- /**
337
- * The comment thread ID.
338
- */
339
- id: string;
340
- /**
341
- * A collection of {@link module:comments/comments/commentsrepository~Comment}s belonging to this thread.
342
- *
343
- * @readonly
344
- */
345
- readonly comments: Collection<Comment>;
346
- constructor(commentsRepository: CommentsRepository, data: {
347
- channelId: string | symbol;
348
- id: string;
349
- context: CommentThreadContext;
350
- attributes: Record<string, unknown>;
351
- unlinkedAt: Date | null;
352
- resolvedAt: Date | null;
353
- resolvedBy: User | null;
354
- isResolvable: boolean;
355
- isSubmitted: boolean;
356
- });
357
- /**
358
- * Sum of {@link module:comments/comments/commentsrepository~Comment#weight weights of all comments} in this thread.
359
- */
360
- get weight(): number;
361
- /**
362
- * The number of {@link module:comments/comments/commentsrepository~Comment comments} in the comment thread.
363
- */
364
- get length(): number;
365
- /**
366
- * Informs if the comment thread is attached to any target at the moment.
367
- */
368
- get isAttached(): boolean;
369
- /**
370
- * Informs if the comment thread has been submitted.
371
- */
372
- get isSubmitted(): boolean;
373
- /**
374
- * Submits the locally created comment thread draft.
375
- */
376
- submit(): void;
377
- /**
378
- * Updates the unlinked date.
379
- */
380
- setUnlinkedAt(unlinkedAt: Date | null): void;
381
- /**
382
- * Resolves the comment thread.
383
- */
384
- resolve({ resolvedAt, resolvedBy, isFromAdapter }?: {
385
- resolvedAt?: Date | undefined;
386
- resolvedBy?: string | undefined;
387
- isFromAdapter?: boolean | undefined;
388
- }): void;
389
- /**
390
- * Reopens the resolved comment thread.
391
- */
392
- reopen({ isFromAdapter }?: {
393
- isFromAdapter?: boolean | undefined;
394
- }): void;
395
- /**
396
- * Set the context on the comment thread.
397
- * This method should be called only when the context has been not set during initialization.
398
- *
399
- * @param context Text context of comment thread.
400
- */
401
- setContext(context: CommentThreadContext): void;
402
- /**
403
- * Adds attribute to the comment thread.
404
- *
405
- * Comment thread attributes are custom data that can be set and used by features
406
- * built around comments. Use it to store your feature data with other comment thread data.
407
- * You can also group multiple values in an object, using dot notation:
408
- *
409
- * ```ts
410
- * commentThread.setAttribute( 'customData.isImportant', true );
411
- * ```
412
- *
413
- * Attributes set on the comment can be accessed through the `attribute` property:
414
- *
415
- * ```ts
416
- * const isImportant = commentThread.attributes.customData.isImportant;
417
- * ```
418
- *
419
- * You can also observe the `attributes` property or bind other properties to it:
420
- *
421
- * ```ts
422
- * myObj.bind( 'customData' ).to( commentThread, 'attributes', attributes => attributes.customData );
423
- * ```
424
- *
425
- * Whenever `setAttribute()` or `removeAttribute()` is called, the `attributes` property
426
- * is re-set and observables are refreshed.
427
- *
428
- * @fires module:comments/comments/commentsrepository~CommentsRepository#event:updateCommentThread
429
- * @param name Attribute name.
430
- * @param value Attribute value.
431
- */
432
- setAttribute(name: string, value: unknown): void;
433
- /**
434
- * Removes a comment attribute.
435
- *
436
- * See also {@link module:comments/comments/commentsrepository~CommentThread#setAttribute}.
437
- *
438
- * @fires module:comments/comments/commentsrepository~CommentsRepository#event:updateCommentThread
439
- * @param name The attribute name.
440
- */
441
- removeAttribute(name: string): void;
442
- /**
443
- * Removes comment thread.
444
- *
445
- * **Note** This method is event-driven. It means it fires an event then a normal priority listener catches
446
- * it and executes an action. It makes it possible to add some actions before and after method will be executed.
447
- *
448
- * @fires module:comments/comments/commentsrepository~RemoveCommentThreadEvent
449
- */
450
- remove({ isFromAdapter }?: {
451
- isFromAdapter?: boolean | undefined;
452
- }): void;
453
- /**
454
- * Creates comment annotations and displays it attached to the given target.
455
- *
456
- * @returns Created annotation.
457
- */
458
- attachTo(target: AnnotationTarget): Annotation;
459
- /**
460
- * Creates a new comment inside the comment thread.
461
- *
462
- * **Note** This method is event-driven. It means it fires an event then a normal priority listener catches
463
- * it and executes an action. It makes it possible to add some actions before and after method will be executed.
464
- *
465
- * See also
466
- * {@link module:comments/comments/commentsrepository~Comment#setAttribute} and
467
- * {@link module:comments/comments/commentsrepository~Comment#removeAttribute}.
468
- *
469
- * @fires module:comments/comments/commentsrepository~CommentsRepository#event:addComment
470
- * @param data Data object.
471
- */
472
- addComment(data: CommentData): void;
473
- /**
474
- * Returns comment of given id.
475
- */
476
- getComment(commentId: string): Comment | null;
477
- toJSON(): CommentThreadDataJSON;
268
+ * Comment thread representation.
269
+ * Stores a list of {@link module:comments/comments/commentsrepository~Comment `Comments`}.
270
+ */
271
+ export declare class CommentThread extends _CommentThreadBase {
272
+ /**
273
+ * Informs if the comment thread is in read-only state (`true`) or not (`false`).
274
+ *
275
+ * @observable
276
+ */
277
+ isReadOnly: boolean;
278
+ /**
279
+ * Informs if the comment thread can be removed by the local user.
280
+ *
281
+ * @observable
282
+ */
283
+ isRemovable: boolean;
284
+ /**
285
+ * Informs if a user has permission to add a new comment to the comment thread.
286
+ *
287
+ * @observable
288
+ */
289
+ canComment: boolean;
290
+ /**
291
+ * Date when the comment thread has been archived.
292
+ *
293
+ * Comment threads become archived after they are {@link #resolvedAt resolved} or {@link #unlinkedAt unlinked}.
294
+ * If the comment thread is resolved and/or unlinked, this value is set to the earliest of the dates. Otherwise, it is `null`.
295
+ *
296
+ * @observable
297
+ */
298
+ archivedAt: Date | null;
299
+ /**
300
+ * The date when the content related to the comment thread was lost (usually, the commented content was removed from the document).
301
+ *
302
+ * @observable
303
+ */
304
+ unlinkedAt: Date | null;
305
+ /**
306
+ * User id which resolved the comment thread.
307
+ *
308
+ * @observable
309
+ */
310
+ resolvedBy: User | null;
311
+ /**
312
+ * Date when the comment thread has been resolved.
313
+ *
314
+ * @observable
315
+ */
316
+ resolvedAt: Date | null;
317
+ /**
318
+ * Informs if the comment thread is resolved.
319
+ *
320
+ * @observable
321
+ */
322
+ readonly isResolved: boolean;
323
+ /**
324
+ * Custom comment thread attributes. See also {@link #setAttribute} and {@link #removeAttribute}.
325
+ *
326
+ * @observable
327
+ */
328
+ attributes: Record<string, unknown>;
329
+ /**
330
+ * The channel where the comment thread was created.
331
+ */
332
+ channelId: string | symbol;
333
+ /**
334
+ * The comment thread ID.
335
+ */
336
+ id: string;
337
+ /**
338
+ * A collection of {@link module:comments/comments/commentsrepository~Comment}s belonging to this thread.
339
+ *
340
+ * @readonly
341
+ */
342
+ readonly comments: Collection<Comment>;
343
+ constructor(commentsRepository: CommentsRepository, data: {
344
+ channelId: string | symbol;
345
+ id: string;
346
+ context: CommentThreadContext;
347
+ attributes: Record<string, unknown>;
348
+ unlinkedAt: Date | null;
349
+ resolvedAt: Date | null;
350
+ resolvedBy: User | null;
351
+ isResolvable: boolean;
352
+ isSubmitted: boolean;
353
+ });
354
+ /**
355
+ * Sum of {@link module:comments/comments/commentsrepository~Comment#weight weights of all comments} in this thread.
356
+ */
357
+ get weight(): number;
358
+ /**
359
+ * The number of {@link module:comments/comments/commentsrepository~Comment comments} in the comment thread.
360
+ */
361
+ get length(): number;
362
+ /**
363
+ * Informs if the comment thread is attached to any target at the moment.
364
+ */
365
+ get isAttached(): boolean;
366
+ /**
367
+ * Informs if the comment thread has been submitted.
368
+ */
369
+ get isSubmitted(): boolean;
370
+ /**
371
+ * Submits the locally created comment thread draft.
372
+ */
373
+ submit(): void;
374
+ /**
375
+ * Updates the unlinked date.
376
+ */
377
+ setUnlinkedAt(unlinkedAt: Date | null): void;
378
+ /**
379
+ * Resolves the comment thread.
380
+ */
381
+ resolve({ resolvedAt, resolvedBy, isFromAdapter }?: Partial<Pick<ResolveCommentThreadEventData, "resolvedAt" | "resolvedBy" | "isFromAdapter">>): void;
382
+ /**
383
+ * Reopens the resolved comment thread.
384
+ */
385
+ reopen({ isFromAdapter }?: Pick<BaseCommentThread, "isFromAdapter">): void;
386
+ /**
387
+ * Set the context on the comment thread.
388
+ * This method should be called only when the context has been not set during initialization.
389
+ *
390
+ * @param context Text context of comment thread.
391
+ */
392
+ setContext(context: CommentThreadContext): void;
393
+ /**
394
+ * Adds attribute to the comment thread.
395
+ *
396
+ * Comment thread attributes are custom data that can be set and used by features
397
+ * built around comments. Use it to store your feature data with other comment thread data.
398
+ * You can also group multiple values in an object, using dot notation:
399
+ *
400
+ * ```ts
401
+ * commentThread.setAttribute( 'customData.isImportant', true );
402
+ * ```
403
+ *
404
+ * Attributes set on the comment can be accessed through the `attribute` property:
405
+ *
406
+ * ```ts
407
+ * const isImportant = commentThread.attributes.customData.isImportant;
408
+ * ```
409
+ *
410
+ * You can also observe the `attributes` property or bind other properties to it:
411
+ *
412
+ * ```ts
413
+ * myObj.bind( 'customData' ).to( commentThread, 'attributes', attributes => attributes.customData );
414
+ * ```
415
+ *
416
+ * Whenever `setAttribute()` or `removeAttribute()` is called, the `attributes` property
417
+ * is re-set and observables are refreshed.
418
+ *
419
+ * @fires module:comments/comments/commentsrepository~CommentsRepository#event:updateCommentThread
420
+ * @param name Attribute name.
421
+ * @param value Attribute value.
422
+ */
423
+ setAttribute(name: string, value: unknown): void;
424
+ /**
425
+ * Removes a comment attribute.
426
+ *
427
+ * See also {@link module:comments/comments/commentsrepository~CommentThread#setAttribute}.
428
+ *
429
+ * @fires module:comments/comments/commentsrepository~CommentsRepository#event:updateCommentThread
430
+ * @param name The attribute name.
431
+ */
432
+ removeAttribute(name: string): void;
433
+ /**
434
+ * Removes comment thread.
435
+ *
436
+ * **Note** This method is event-driven. It means it fires an event then a normal priority listener catches
437
+ * it and executes an action. It makes it possible to add some actions before and after method will be executed.
438
+ *
439
+ * @fires module:comments/comments/commentsrepository~RemoveCommentThreadEvent
440
+ */
441
+ remove({ isFromAdapter }?: Pick<BaseCommentThread, "isFromAdapter">): void;
442
+ /**
443
+ * Creates comment annotations and displays it attached to the given target.
444
+ *
445
+ * @returns Created annotation.
446
+ */
447
+ attachTo(target: AnnotationTarget): Annotation;
448
+ /**
449
+ * Creates a new comment inside the comment thread.
450
+ *
451
+ * **Note** This method is event-driven. It means it fires an event then a normal priority listener catches
452
+ * it and executes an action. It makes it possible to add some actions before and after method will be executed.
453
+ *
454
+ * See also
455
+ * {@link module:comments/comments/commentsrepository~Comment#setAttribute} and
456
+ * {@link module:comments/comments/commentsrepository~Comment#removeAttribute}.
457
+ *
458
+ * @fires module:comments/comments/commentsrepository~CommentsRepository#event:addComment
459
+ * @param data Data object.
460
+ */
461
+ addComment(data: CommentData): void;
462
+ /**
463
+ * Returns comment of given id.
464
+ */
465
+ getComment(commentId: string): Comment | null;
466
+ toJSON(): CommentThreadDataJSON;
478
467
  }
479
- declare const Comment_base: {
480
- new (): import("@ckeditor/ckeditor5-utils").Observable;
481
- prototype: import("@ckeditor/ckeditor5-utils").Observable;
482
- };
483
468
  /**
484
- * Single comment representation. A part of a {@link module:comments/comments/commentsrepository~CommentThread commentThread}.
485
- */
486
- export declare class Comment extends /* #__PURE__ -- @preserve */ Comment_base {
487
- /**
488
- * When is set to `true`, editing the comment is blocked.
489
- *
490
- * @observable
491
- */
492
- readonly isEditable: boolean;
493
- /**
494
- * When is set to `false`, removing the comment is blocked.
495
- *
496
- * @observable
497
- */
498
- readonly isRemovable: boolean;
499
- /**
500
- * The read-only state inherited from the parent {@link module:comments/comments/commentsrepository~CommentThread}.
501
- * When is set to `true`, then removing and editing the comment thread is blocked.
502
- *
503
- * In contrast to {@link #isEditable} and {@link #isRemovable}, this state can be used to
504
- * hide some UI parts instead of temporarily disabling them.
505
- *
506
- * @observable
507
- */
508
- readonly isReadOnly: boolean;
509
- /**
510
- * The comment content.
511
- */
512
- content: string;
513
- /**
514
- * Date when the comment was made.
515
- *
516
- * Usually the same as {@link #createdAt `createdAt`} but may be different in some cases
517
- * (e.g. when comment was added from an external source).
518
- *
519
- * @observable
520
- */
521
- authoredAt: Date;
522
- /**
523
- * The date when the comment thread was resolved or `null` if it is not resolved.
524
- *
525
- * @observable
526
- */
527
- resolvedAt: Date | null;
528
- /**
529
- * Custom comment attributes. See also {@link #setAttribute} and {@link #removeAttribute}.
530
- *
531
- * @observable
532
- */
533
- attributes: Record<string, any>;
534
- /**
535
- * The comment ID.
536
- */
537
- readonly id: string;
538
- /**
539
- * The ID of the comment thread that contains this comment.
540
- */
541
- readonly threadId: string;
542
- /**
543
- * The comment author.
544
- */
545
- readonly author: User;
546
- /**
547
- * The user which saved the comment data in the database.
548
- *
549
- * Usually the same as author but may be different in some cases (e.g. when comment was added from an external source).
550
- */
551
- readonly creator: User;
552
- /**
553
- * The flag indicating whether the comment comes from an external source.
554
- */
555
- readonly isExternal: boolean;
556
- /**
557
- * Date when the comment was saved in the database.
558
- */
559
- createdAt: Date;
560
- /**
561
- * @param commentsRepository
562
- * @param data Configuration object.
563
- * @param data.id Comment id.
564
- * @param data.threadId Comment thread id.
565
- * @param data.content Comment content.
566
- * @param data.author Comment author.
567
- * @param data.creator The user which saved the comment data.
568
- * Usually the same as author but may be different in some cases (e.g. when comment was added from an external source).
569
- * @param data.createdAt Date when the comment was saved in the database.
570
- * @param data.authoredAt Date when the comment was made.
571
- * @param data.attributes Custom comment attributes. See also
572
- * {@link module:comments/comments/commentsrepository~Comment#setAttribute} and
573
- * {@link module:comments/comments/commentsrepository~Comment#removeAttribute}.
574
- */
575
- constructor(commentsRepository: CommentsRepository, data: {
576
- id: string;
577
- threadId: string;
578
- content: string;
579
- author: User;
580
- creator: User;
581
- createdAt: Date;
582
- authoredAt: Date;
583
- attributes: Record<string, unknown>;
584
- });
585
- /**
586
- * The comment weight.
587
- *
588
- * It is equal to the length of the comment content, however it is never smaller than `200`.
589
- * This limit is set to avoid a long list of very short not collapsed comments.
590
- */
591
- get weight(): number;
592
- /**
593
- * Updates the comment with provided data.
594
- *
595
- * **Note:** This method fires the {@link module:comments/comments/commentsrepository~CommentsRepository#event:updateComment}
596
- * event and the default behavior is added as a normal priority listener. It makes it
597
- * possible to cancel the method or call some custom code before or after the default
598
- * behavior is executed.
599
- *
600
- * @fires module:comments/comments/commentsrepository~CommentsRepository#event:updateComment
601
- * @param data Data object. Available properties:
602
- *
603
- * - `content` — Comment content.
604
- * - `createdAt` — Creation date.
605
- * - `attributes` — Custom comment attributes. See also
606
- * {@link module:comments/comments/commentsrepository~Comment#setAttribute} and
607
- * {@link module:comments/comments/commentsrepository~Comment#removeAttribute}.
608
- * - `isFromAdapter`
609
- */
610
- update(data: UpdateCommentData): void;
611
- /**
612
- * Adds attribute to the comment.
613
- *
614
- * Comment attributes are custom data that can be set and used by features
615
- * built around comments. Use it to store your feature data with other comment data.
616
- *
617
- * comment.setAttribute( 'isImportant', true );
618
- *
619
- * You can group multiple values in an object, using dot notation:
620
- *
621
- * comment.setAttribute( 'customData.type', 'image' );
622
- * comment.setAttribute( 'customData.src', 'foo.jpg' );
623
- *
624
- * Attributes set on the comment can be accessed through the `attribute` property:
625
- *
626
- * const isImportant = comment.attributes.isImportant;
627
- * const type = comment.attributes.customData.type;
628
- *
629
- * You can also observe the `attributes` property or bind other properties to it:
630
- *
631
- * myObj.bind( 'customData' ).to( comment, 'attributes', attributes => attributes.customData );
632
- *
633
- * Whenever `setAttribute()` or `removeAttribute()` is called, the `attributes` property
634
- * is re-set and observables are refreshed.
635
- *
636
- * @fires module:comments/comments/commentsrepository~CommentsRepository#event:updateComment
637
- * @param name Attribute name.
638
- * @param value Attribute value.
639
- */
640
- setAttribute(name: string, value: unknown): void;
641
- /**
642
- * Removes a comment attribute.
643
- *
644
- * See also {@link module:comments/comments/commentsrepository~Comment#setAttribute}.
645
- *
646
- * @fires module:comments/comments/commentsrepository~CommentsRepository#event:updateComment
647
- * @param name The attribute name.
648
- */
649
- removeAttribute(name: string): void;
650
- /**
651
- * Removes the comment.
652
- *
653
- * **Note:** This method fires the {@link module:comments/comments/commentsrepository~CommentsRepository#event:updateComment}
654
- * event and the default behavior is added as a normal priority listener. It makes it
655
- * possible to cancel the method or call some custom code before or after the default
656
- * behavior is executed.
657
- *
658
- * @fires module:comments/comments/commentsrepository~CommentsRepository#event:removeComment
659
- * @param data.isFromAdapter A flag describing whether the comment was
660
- * updated from an adapter (`true`) or from the UI (`false`). If set to `true`, the adapter will not be called.
661
- */
662
- remove(data?: {
663
- isFromAdapter?: boolean;
664
- }): void;
665
- toJSON(): CommentDataJSON;
666
- /**
667
- * Destroys the comment instance.
668
- */
669
- destroy(): void;
469
+ * Single comment representation. A part of a {@link module:comments/comments/commentsrepository~CommentThread commentThread}.
470
+ */
471
+ export declare class Comment extends _CommentBase {
472
+ /**
473
+ * When is set to `true`, editing the comment is blocked.
474
+ *
475
+ * @observable
476
+ */
477
+ readonly isEditable: boolean;
478
+ /**
479
+ * When is set to `false`, removing the comment is blocked.
480
+ *
481
+ * @observable
482
+ */
483
+ readonly isRemovable: boolean;
484
+ /**
485
+ * The read-only state inherited from the parent {@link module:comments/comments/commentsrepository~CommentThread}.
486
+ * When is set to `true`, then removing and editing the comment thread is blocked.
487
+ *
488
+ * In contrast to {@link #isEditable} and {@link #isRemovable}, this state can be used to
489
+ * hide some UI parts instead of temporarily disabling them.
490
+ *
491
+ * @observable
492
+ */
493
+ readonly isReadOnly: boolean;
494
+ /**
495
+ * The comment content.
496
+ */
497
+ content: string;
498
+ /**
499
+ * Date when the comment was made.
500
+ *
501
+ * Usually the same as {@link #createdAt `createdAt`} but may be different in some cases
502
+ * (e.g. when comment was added from an external source).
503
+ *
504
+ * @observable
505
+ */
506
+ authoredAt: Date;
507
+ /**
508
+ * The date when the comment thread was resolved or `null` if it is not resolved.
509
+ *
510
+ * @observable
511
+ */
512
+ resolvedAt: Date | null;
513
+ /**
514
+ * Custom comment attributes. See also {@link #setAttribute} and {@link #removeAttribute}.
515
+ *
516
+ * @observable
517
+ */
518
+ attributes: Record<string, any>;
519
+ /**
520
+ * The comment ID.
521
+ */
522
+ readonly id: string;
523
+ /**
524
+ * The ID of the comment thread that contains this comment.
525
+ */
526
+ readonly threadId: string;
527
+ /**
528
+ * The comment author.
529
+ */
530
+ readonly author: User;
531
+ /**
532
+ * The user which saved the comment data in the database.
533
+ *
534
+ * Usually the same as author but may be different in some cases (e.g. when comment was added from an external source).
535
+ */
536
+ readonly creator: User;
537
+ /**
538
+ * Date when the comment was saved in the database.
539
+ */
540
+ createdAt: Date;
541
+ /**
542
+ * @param commentsRepository
543
+ * @param data Configuration object.
544
+ * @param data.id Comment id.
545
+ * @param data.threadId Comment thread id.
546
+ * @param data.content Comment content.
547
+ * @param data.author Comment author.
548
+ * @param data.creator The user which saved the comment data.
549
+ * Usually the same as author but may be different in some cases (e.g. when comment was added from an external source).
550
+ * @param data.createdAt Date when the comment was saved in the database.
551
+ * @param data.authoredAt Date when the comment was made.
552
+ * @param data.attributes Custom comment attributes. See also
553
+ * {@link module:comments/comments/commentsrepository~Comment#setAttribute} and
554
+ * {@link module:comments/comments/commentsrepository~Comment#removeAttribute}.
555
+ */
556
+ constructor(commentsRepository: CommentsRepository, data: {
557
+ id: string;
558
+ threadId: string;
559
+ content: string;
560
+ author: User;
561
+ creator: User;
562
+ createdAt: Date;
563
+ authoredAt: Date;
564
+ attributes: Record<string, unknown>;
565
+ });
566
+ /**
567
+ * The flag indicating whether the comment comes from an external source.
568
+ */
569
+ get isExternal(): boolean;
570
+ /**
571
+ * The comment weight.
572
+ *
573
+ * It is equal to the length of the comment content, however it is never smaller than `200`.
574
+ * This limit is set to avoid a long list of very short not collapsed comments.
575
+ */
576
+ get weight(): number;
577
+ /**
578
+ * Updates the comment with provided data.
579
+ *
580
+ * **Note:** This method fires the {@link module:comments/comments/commentsrepository~CommentsRepository#event:updateComment}
581
+ * event and the default behavior is added as a normal priority listener. It makes it
582
+ * possible to cancel the method or call some custom code before or after the default
583
+ * behavior is executed.
584
+ *
585
+ * @fires module:comments/comments/commentsrepository~CommentsRepository#event:updateComment
586
+ * @param data Data object. Available properties:
587
+ *
588
+ * - `content` — Comment content.
589
+ * - `createdAt` — Creation date.
590
+ * - `attributes` — Custom comment attributes. See also
591
+ * {@link module:comments/comments/commentsrepository~Comment#setAttribute} and
592
+ * {@link module:comments/comments/commentsrepository~Comment#removeAttribute}.
593
+ * - `isFromAdapter`
594
+ */
595
+ update(data: UpdateCommentData): void;
596
+ /**
597
+ * Adds attribute to the comment.
598
+ *
599
+ * Comment attributes are custom data that can be set and used by features
600
+ * built around comments. Use it to store your feature data with other comment data.
601
+ *
602
+ * comment.setAttribute( 'isImportant', true );
603
+ *
604
+ * You can group multiple values in an object, using dot notation:
605
+ *
606
+ * comment.setAttribute( 'customData.type', 'image' );
607
+ * comment.setAttribute( 'customData.src', 'foo.jpg' );
608
+ *
609
+ * Attributes set on the comment can be accessed through the `attribute` property:
610
+ *
611
+ * const isImportant = comment.attributes.isImportant;
612
+ * const type = comment.attributes.customData.type;
613
+ *
614
+ * You can also observe the `attributes` property or bind other properties to it:
615
+ *
616
+ * myObj.bind( 'customData' ).to( comment, 'attributes', attributes => attributes.customData );
617
+ *
618
+ * Whenever `setAttribute()` or `removeAttribute()` is called, the `attributes` property
619
+ * is re-set and observables are refreshed.
620
+ *
621
+ * @fires module:comments/comments/commentsrepository~CommentsRepository#event:updateComment
622
+ * @param name Attribute name.
623
+ * @param value Attribute value.
624
+ */
625
+ setAttribute(name: string, value: unknown): void;
626
+ /**
627
+ * Removes a comment attribute.
628
+ *
629
+ * See also {@link module:comments/comments/commentsrepository~Comment#setAttribute}.
630
+ *
631
+ * @fires module:comments/comments/commentsrepository~CommentsRepository#event:updateComment
632
+ * @param name The attribute name.
633
+ */
634
+ removeAttribute(name: string): void;
635
+ /**
636
+ * Removes the comment.
637
+ *
638
+ * **Note:** This method fires the {@link module:comments/comments/commentsrepository~CommentsRepository#event:updateComment}
639
+ * event and the default behavior is added as a normal priority listener. It makes it
640
+ * possible to cancel the method or call some custom code before or after the default
641
+ * behavior is executed.
642
+ *
643
+ * @fires module:comments/comments/commentsrepository~CommentsRepository#event:removeComment
644
+ * @param data.isFromAdapter A flag describing whether the comment was
645
+ * updated from an adapter (`true`) or from the UI (`false`). If set to `true`, the adapter will not be called.
646
+ */
647
+ remove(data?: {
648
+ isFromAdapter?: boolean;
649
+ }): void;
650
+ toJSON(): CommentDataJSON;
651
+ /**
652
+ * Destroys the comment instance.
653
+ */
654
+ destroy(): void;
670
655
  }
671
656
  export type CommentThreadContext = null | {
672
- type: string;
673
- value: unknown;
657
+ type: string;
658
+ value: unknown;
674
659
  };
675
660
  /**
676
- * @param channelId The ID of a document or context that the comment thread is handled.
677
- * @param threadId The ID of the comment thread.
678
- * @param isFromAdapter A flag describing whether the operation was done on a remote client (`true`) or a local one (`false`).
679
- */
661
+ * @param channelId The ID of a document or context that the comment thread is handled.
662
+ * @param threadId The ID of the comment thread.
663
+ * @param isFromAdapter A flag describing whether the operation was done on a remote client (`true`) or a local one (`false`).
664
+ */
680
665
  export interface BaseCommentThread {
681
- channelId: string | symbol;
682
- threadId: string;
683
- isFromAdapter?: boolean;
666
+ channelId: string | symbol;
667
+ threadId: string;
668
+ isFromAdapter?: boolean;
684
669
  }
685
670
  /**
686
- * @param commentId The comment ID.
687
- */
671
+ * @param commentId The comment ID.
672
+ */
688
673
  export interface BaseComment extends BaseCommentThread {
689
- commentId: string;
674
+ commentId: string;
690
675
  }
691
676
  /**
692
- * @param content The comment content.
693
- * @param attributes Comment custom attributes.
694
- */
677
+ * @param content The comment content.
678
+ * @param attributes Comment custom attributes.
679
+ */
695
680
  export interface BaseCommentData {
696
- content: string;
697
- attributes: Record<string, any>;
681
+ content: string;
682
+ attributes: Record<string, any>;
698
683
  }
699
684
  /**
700
- * Fired whenever a comment thread is added to the comments repository.
701
- *
702
- * The event name includes `channelId` so it is possible to listen only
703
- * on changes happening in the specified channel.
704
- *
705
- * ```ts
706
- * const channelId = 'foo';
707
- *
708
- * commentsRepository.on( `addCommentThread:${ channelId }`, ( evt, data ) => {
709
- * console.log( evt, data );
710
- * } );
711
- * ```
712
- *
713
- * @eventName ~CommentsRepository#addCommentThread
714
- */
685
+ * Fired whenever a comment thread is added to the comments repository.
686
+ *
687
+ * The event name includes `channelId` so it is possible to listen only
688
+ * on changes happening in the specified channel.
689
+ *
690
+ * ```ts
691
+ * const channelId = 'foo';
692
+ *
693
+ * commentsRepository.on( `addCommentThread:${ channelId }`, ( evt, data ) => {
694
+ * console.log( evt, data );
695
+ * } );
696
+ * ```
697
+ *
698
+ * @eventName ~CommentsRepository#addCommentThread
699
+ */
715
700
  export type AddCommentThreadEvent = {
716
- name: string;
717
- args: [Required<AddCommentThreadEventData>];
701
+ name: string;
702
+ args: [Required<AddCommentThreadEventData>];
718
703
  };
719
704
  /**
720
- * @param context The comment ID.
721
- * @param attributes Comment thread custom attributes.
722
- * @param resolvedAt ID of the comment author.
723
- * @param resolvedBy The comment creation date.
724
- */
705
+ * @param context The comment ID.
706
+ * @param attributes Comment thread custom attributes.
707
+ * @param resolvedAt ID of the comment author.
708
+ * @param resolvedBy The comment creation date.
709
+ */
725
710
  export type CommentThreadData = BaseCommentThread & Partial<{
726
- context: CommentThreadContext;
727
- attributes: Record<string, any>;
728
- unlinkedAt: Date | null;
729
- resolvedAt: Date | null;
730
- resolvedBy: string | null;
711
+ context: CommentThreadContext;
712
+ attributes: Record<string, any>;
713
+ unlinkedAt: Date | null;
714
+ resolvedAt: Date | null;
715
+ resolvedBy: string | null;
731
716
  }>;
732
717
  /**
733
- * @param comments Comments in the comment thread.
734
- * @param target The target that the comment balloon should be attached to.
735
- */
718
+ * @param comments Comments in the comment thread.
719
+ * @param target The target that the comment balloon should be attached to.
720
+ */
736
721
  export type AddCommentThreadEventData = CommentThreadData & {
737
- comments?: Array<CommentData>;
738
- target?: AnnotationTarget;
739
- isResolvable?: boolean;
740
- isSubmitted?: boolean;
722
+ comments?: Array<CommentData>;
723
+ target?: AnnotationTarget;
724
+ isResolvable?: boolean;
725
+ isSubmitted?: boolean;
741
726
  };
742
727
  /**
743
- * Fired whenever a new comment thread is submitted and occurs after creating the first comment.
744
- *
745
- * The event name includes `channelId` so it is possible to listen only
746
- * on changes happening in the specified channel.
747
- *
748
- * ```ts
749
- * const channelId = 'foo';
750
- *
751
- * commentsRepository.on( `submitCommentThread:${ channelId }`, ( evt, data ) => {
752
- * console.log( evt, data );
753
- * } );
754
- * ```
755
- *
756
- * @eventName ~CommentsRepository#submitCommentThread
757
- */
728
+ * Fired whenever a new comment thread is submitted and occurs after creating the first comment.
729
+ *
730
+ * The event name includes `channelId` so it is possible to listen only
731
+ * on changes happening in the specified channel.
732
+ *
733
+ * ```ts
734
+ * const channelId = 'foo';
735
+ *
736
+ * commentsRepository.on( `submitCommentThread:${ channelId }`, ( evt, data ) => {
737
+ * console.log( evt, data );
738
+ * } );
739
+ * ```
740
+ *
741
+ * @eventName ~CommentsRepository#submitCommentThread
742
+ */
758
743
  export type SubmitCommentThreadEvent = {
759
- name: string;
760
- args: [BaseCommentThread];
744
+ name: string;
745
+ args: [BaseCommentThread];
761
746
  };
762
747
  /**
763
- * Fired whenever a comment thread is updated in comments repository.
764
- *
765
- * The event name includes `channelId` so it is possible to listen only
766
- * on changes happening in the specified channel.
767
- *
768
- * @eventName ~CommentsRepository#updateCommentThread
769
- */
748
+ * Fired whenever a comment thread is updated in comments repository.
749
+ *
750
+ * The event name includes `channelId` so it is possible to listen only
751
+ * on changes happening in the specified channel.
752
+ *
753
+ * @eventName ~CommentsRepository#updateCommentThread
754
+ */
770
755
  export type UpdateCommentThreadEvent = {
771
- name: string;
772
- args: [UpdateCommentThreadEventData];
756
+ name: string;
757
+ args: [UpdateCommentThreadEventData];
773
758
  };
774
- export type UpdateCommentThreadEventData = Omit<CommentThreadData, 'resolvedAt' | 'resolvedBy'>;
759
+ export type UpdateCommentThreadEventData = Omit<CommentThreadData, "resolvedAt" | "resolvedBy">;
775
760
  /**
776
- * Fired whenever a comment thread is resolved.
777
- *
778
- * The event name includes `channelId` so it is possible to listen only
779
- * on changes happening in the specified channel.
780
- *
781
- * ```ts
782
- * const channelId = 'foo';
783
- *
784
- * commentsRepository.on( `resolveCommentThread:${ channelId }`, ( evt, data ) => {
785
- * console.log( evt, data );
786
- * } );
787
- * ```
788
- *
789
- * @eventName ~CommentsRepository#resolveCommentThread
790
- */
761
+ * Fired whenever a comment thread is resolved.
762
+ *
763
+ * The event name includes `channelId` so it is possible to listen only
764
+ * on changes happening in the specified channel.
765
+ *
766
+ * ```ts
767
+ * const channelId = 'foo';
768
+ *
769
+ * commentsRepository.on( `resolveCommentThread:${ channelId }`, ( evt, data ) => {
770
+ * console.log( evt, data );
771
+ * } );
772
+ * ```
773
+ *
774
+ * @eventName ~CommentsRepository#resolveCommentThread
775
+ */
791
776
  export type ResolveCommentThreadEvent = {
792
- name: string;
793
- args: [ResolveCommentThreadEventData];
777
+ name: string;
778
+ args: [ResolveCommentThreadEventData];
794
779
  };
795
780
  export type ResolveCommentThreadEventData = BaseCommentThread & {
796
- resolvedAt: Date | null;
797
- resolvedBy: string | null;
781
+ resolvedAt: Date | null;
782
+ resolvedBy: string | null;
798
783
  };
799
784
  /**
800
- * Fired whenever a comment thread is reopened.
801
- *
802
- * The event name includes `channelId` so it is possible to listen only
803
- * on changes happening in the specified channel.
804
- *
805
- * ```ts
806
- * const channelId = 'foo';
807
- *
808
- * commentsRepository.on( `reopenCommentThread:${ channelId }`, ( evt, data ) => {
809
- * console.log( evt, data );
810
- * } );
811
- * ```
812
- *
813
- * @eventName ~CommentsRepository#reopenCommentThread
814
- */
785
+ * Fired whenever a comment thread is reopened.
786
+ *
787
+ * The event name includes `channelId` so it is possible to listen only
788
+ * on changes happening in the specified channel.
789
+ *
790
+ * ```ts
791
+ * const channelId = 'foo';
792
+ *
793
+ * commentsRepository.on( `reopenCommentThread:${ channelId }`, ( evt, data ) => {
794
+ * console.log( evt, data );
795
+ * } );
796
+ * ```
797
+ *
798
+ * @eventName ~CommentsRepository#reopenCommentThread
799
+ */
815
800
  export type ReopenCommentThreadEvent = {
816
- name: string;
817
- args: [BaseCommentThread];
801
+ name: string;
802
+ args: [BaseCommentThread];
818
803
  };
819
804
  /**
820
- * Fired whenever a comment thread is removed from the comments repository.
821
- *
822
- * The event name includes `channelId` so it is possible to listen only
823
- * on changes happening in the specified channel.
824
- *
825
- * ```ts
826
- * const channelId = 'foo';
827
- *
828
- * commentsRepository.on( `removeCommentThread:${ channelId }`, ( evt, data ) => {
829
- * console.log( evt, data );
830
- * } );
831
- * ```
832
- *
833
- * @eventName ~CommentsRepository#removeCommentThread
834
- */
805
+ * Fired whenever a comment thread is removed from the comments repository.
806
+ *
807
+ * The event name includes `channelId` so it is possible to listen only
808
+ * on changes happening in the specified channel.
809
+ *
810
+ * ```ts
811
+ * const channelId = 'foo';
812
+ *
813
+ * commentsRepository.on( `removeCommentThread:${ channelId }`, ( evt, data ) => {
814
+ * console.log( evt, data );
815
+ * } );
816
+ * ```
817
+ *
818
+ * @eventName ~CommentsRepository#removeCommentThread
819
+ */
835
820
  export type RemoveCommentThreadEvent = {
836
- name: string;
837
- args: [BaseCommentThread];
821
+ name: string;
822
+ args: [BaseCommentThread];
838
823
  };
839
824
  /**
840
- * Fired whenever a comment is added.
841
- *
842
- * The event name includes `channelId` so it is possible to listen only
843
- * on changes happening in the specified channel.
844
- *
845
- * It is also possible to listen to events from the given thread ID by appending `:[threadId]` part to the event name
846
- *
847
- * ```ts
848
- * const channelId = 'foo';
849
- * const threadId = '1234';
850
- *
851
- * commentsRepository.on( `addComment:${ channelId }:${ threadId }`, ( evt, data ) => {
852
- * console.log( evt, data );
853
- * } );
854
- * ```
855
- *
856
- * @eventName ~CommentsRepository#addComment
857
- */
825
+ * Fired whenever a comment is added.
826
+ *
827
+ * The event name includes `channelId` so it is possible to listen only
828
+ * on changes happening in the specified channel.
829
+ *
830
+ * It is also possible to listen to events from the given thread ID by appending `:[threadId]` part to the event name
831
+ *
832
+ * ```ts
833
+ * const channelId = 'foo';
834
+ * const threadId = '1234';
835
+ *
836
+ * commentsRepository.on( `addComment:${ channelId }:${ threadId }`, ( evt, data ) => {
837
+ * console.log( evt, data );
838
+ * } );
839
+ * ```
840
+ *
841
+ * @eventName ~CommentsRepository#addComment
842
+ */
858
843
  export type AddCommentEvent = {
859
- name: string;
860
- args: [CommentEventData];
844
+ name: string;
845
+ args: [CommentEventData];
861
846
  };
862
847
  /**
863
- * @param commentId The comment ID.
864
- * @param authorId ID of the comment author.
865
- * @param createdAt The comment creation date.
866
- * @param isFromAdapter A flag describing whether the comment was updated on a remote client (`true`) or a local one (`false`).
867
- */
848
+ * @param commentId The comment ID.
849
+ * @param authorId ID of the comment author.
850
+ * @param createdAt The comment creation date.
851
+ * @param isFromAdapter A flag describing whether the comment was updated on a remote client (`true`) or a local one (`false`).
852
+ */
868
853
  export type CommentData = BaseCommentData & {
869
- commentId?: string;
870
- authorId: string;
871
- createdAt: Date;
872
- isFromAdapter?: boolean;
854
+ commentId?: string;
855
+ authorId: string;
856
+ createdAt: Date;
857
+ isFromAdapter?: boolean;
873
858
  };
874
859
  export type CommentEventData = BaseCommentThread & CommentData;
875
860
  /**
876
- * Fired whenever a comment is updated.
877
- *
878
- * The event name includes `channelId` so it is possible to listen only
879
- * to changes happening in the specified channel.
880
- *
881
- * It is also possible to listen to events from the given thread ID by appending `:[threadId]` part to the event name
882
- *
883
- * ```ts
884
- * const channelId = 'foo';
885
- * const threadId = '1234';
886
- *
887
- * commentsRepository.on( `updateComment:${ channelId }:${ threadId }`, ( evt, data ) => {
888
- * console.log( evt, data );
889
- * } );
890
- * ```
891
- *
892
- * @eventName ~CommentsRepository#updateComment
893
- */
861
+ * Fired whenever a comment is updated.
862
+ *
863
+ * The event name includes `channelId` so it is possible to listen only
864
+ * to changes happening in the specified channel.
865
+ *
866
+ * It is also possible to listen to events from the given thread ID by appending `:[threadId]` part to the event name
867
+ *
868
+ * ```ts
869
+ * const channelId = 'foo';
870
+ * const threadId = '1234';
871
+ *
872
+ * commentsRepository.on( `updateComment:${ channelId }:${ threadId }`, ( evt, data ) => {
873
+ * console.log( evt, data );
874
+ * } );
875
+ * ```
876
+ *
877
+ * @eventName ~CommentsRepository#updateComment
878
+ */
894
879
  export type UpdateCommentEvent = {
895
- name: string;
896
- args: [UpdateCommentEventData];
880
+ name: string;
881
+ args: [UpdateCommentEventData];
897
882
  };
898
883
  export type UpdateCommentData = Partial<CommentEventData>;
899
884
  export type UpdateCommentEventData = UpdateCommentData & BaseComment;
900
885
  /**
901
- * Fired whenever a comment is removed.
902
- *
903
- * The event name includes `channelId` so it is possible to listen only
904
- * to changes happening in the specified channel.
905
- *
906
- * It is also possible to listen to events from the given thread ID by appending `:[threadId]` part to the event name
907
- *
908
- * ```ts
909
- * const channelId = 'foo';
910
- * const threadId = '1234';
911
- *
912
- * commentsRepository.on( `removeComment:${ channelId }:${ threadId }`, ( evt, data ) => {
913
- * console.log( evt, data );
914
- * } );
915
- * ```
916
- *
917
- * @eventName ~CommentsRepository#removeComment
918
- */
886
+ * Fired whenever a comment is removed.
887
+ *
888
+ * The event name includes `channelId` so it is possible to listen only
889
+ * to changes happening in the specified channel.
890
+ *
891
+ * It is also possible to listen to events from the given thread ID by appending `:[threadId]` part to the event name
892
+ *
893
+ * ```ts
894
+ * const channelId = 'foo';
895
+ * const threadId = '1234';
896
+ *
897
+ * commentsRepository.on( `removeComment:${ channelId }:${ threadId }`, ( evt, data ) => {
898
+ * console.log( evt, data );
899
+ * } );
900
+ * ```
901
+ *
902
+ * @eventName ~CommentsRepository#removeComment
903
+ */
919
904
  export type RemoveCommentEvent = {
920
- name: string;
921
- args: [BaseComment];
905
+ name: string;
906
+ args: [BaseComment];
922
907
  };
923
- export type CommentDataJSON = Omit<CommentData, 'isFromAdapter'>;
908
+ export type CommentDataJSON = Omit<CommentData, "isFromAdapter">;
924
909
  export type CommentThreadDataJSON = {
925
- threadId: string;
926
- context: CommentThreadContext;
927
- unlinkedAt: Date | null;
928
- resolvedAt: Date | null;
929
- resolvedBy: string | null;
930
- archivedAt: Date | null;
931
- comments: Array<CommentDataJSON>;
932
- attributes: Record<string, unknown>;
910
+ threadId: string;
911
+ context: CommentThreadContext;
912
+ unlinkedAt: Date | null;
913
+ resolvedAt: Date | null;
914
+ resolvedBy: string | null;
915
+ archivedAt: Date | null;
916
+ comments: Array<CommentDataJSON>;
917
+ attributes: Record<string, unknown>;
933
918
  };
934
919
  /**
935
- * Comments adapter.
936
- *
937
- * The comments adapter is an object that communicates asynchronously with the data source to fetch or save
938
- * the comment data. It is used internally by the comments feature whenever a comment is loaded, created or deleted.
939
- * The adapter is optional. You might need to provide it if you are {@glink features/collaboration/comments/comments-integration
940
- * using the comments feature without real-time collaboration}.
941
- * To set the adapter, overwrite the `CommentsRepository#adapter` property.
942
- */
920
+ * Comments adapter.
921
+ *
922
+ * The comments adapter is an object that communicates asynchronously with the data source to fetch or save
923
+ * the comment data. It is used internally by the comments feature whenever a comment is loaded, created or deleted.
924
+ * The adapter is optional. You might need to provide it if you are {@glink features/collaboration/comments/comments-integration
925
+ * using the comments feature without real-time collaboration}.
926
+ * To set the adapter, overwrite the `CommentsRepository#adapter` property.
927
+ */
943
928
  export interface CommentsAdapter {
944
- /**
945
- * Called whenever a new comment thread is created.
946
- *
947
- * The object which is passed as a parameter can contain the following properties:
948
- * * channelId: string | symbol;
949
- * * threadId: string;
950
- * * context?: {@link module:comments/comments/commentsrepository~CommentThreadContext CommentThreadContext};
951
- * * comments?: Array<{@link module:comments/comments/commentsrepository~CommentDataJSON CommentDataJSON}>;
952
- * * resolvedAt?: Date | null;
953
- * * resolvedBy?: string | null;
954
- * * attributes?: Record<string, any> | null;
955
- *
956
- * It should return a promise that resolves with the new comment thread data.
957
- * The resolved data object should contain the following properties:
958
- * * threadId: string;
959
- * * comments: Array<\{ commentId: string; createdAt: Date; \}>;
960
- */
961
- addCommentThread: (data: Omit<CommentThreadData, 'isFromAdapter'> & {
962
- comments: Array<CommentDataJSON>;
963
- }) => Promise<{
964
- threadId: string;
965
- comments: Array<{
966
- commentId: string;
967
- createdAt: Date;
968
- }>;
969
- }>;
970
- /**
971
- * Called when the editor needs the data for a comment thread.
972
- *
973
- * It should return a promise that resolves with the comment thread data.
974
- * The resolved data object should contain the following properties:
975
- * * threadId: string;
976
- * * comments: Array<\{ commentId?: string; authorId: string; createdAt: Date; content: string; attributes: Record<string, any>; \}>;
977
- * * resolvedAt?: Date | null;
978
- * * resolvedBy?: string | null;
979
- * * attributes: Record<string, unknown>;
980
- *
981
- * @param data.channelId The ID of the document or context to which the comment is added.
982
- * @param data.threadId The ID of the comment thread that the comment is added to.
983
- */
984
- getCommentThread: (data: Omit<BaseCommentThread, 'isFromAdapter'>) => Promise<{
985
- threadId: string;
986
- comments: Array<CommentData>;
987
- resolvedAt?: Date | null;
988
- resolvedBy?: string | null;
989
- attributes: Record<string, unknown>;
990
- } | null>;
991
- /**
992
- * Called each time the user changes the existing comment thread.
993
- *
994
- * Keep in mind that for security reasons, the `authorId`, `createdAt`, `resolvedBy` and `resolvedAt` properties
995
- * are not passed in the `updateCommentThread()` call and you should not set them as a result of this call.
996
- *
997
- * It updates the comment data in the database and returns a promise
998
- * that will be resolved when the update is completed.
999
- *
1000
- * The object which is passed as a parameter can contain the following properties:
1001
- * * channelId: string | symbol;
1002
- * * threadId: string;
1003
- * * context?: {@link module:comments/comments/commentsrepository~CommentThreadContext};
1004
- * * attributes?: Record<string, any> | null;
1005
- */
1006
- updateCommentThread: (data: Omit<UpdateCommentThreadEventData, 'isFromAdapter'>) => Promise<void>;
1007
- /**
1008
- * Called each time the user resolves a comment thread.
1009
- *
1010
- * Should set `resolvedAt` and `resolvedBy` properties in your database and should resolve with an object
1011
- * containing these two properties and returns a promise that will be resolved when the operation is completed.
1012
- *
1013
- * The resolved data object should contain the following properties:
1014
- * * threadId: string;
1015
- * * resolvedAt: Date;
1016
- * * resolvedBy: string;
1017
- *
1018
- * @param data.channelId The ID of the document or context that the comment thread is removed from.
1019
- * @param data.threadId The ID of the thread to remove.
1020
- */
1021
- resolveCommentThread: (data: Omit<BaseCommentThread, 'isFromAdapter'>) => Promise<{
1022
- threadId: string;
1023
- resolvedAt: Date;
1024
- resolvedBy: string;
1025
- }>;
1026
- /**
1027
- * Called when the user reopens a resolved comment thread.
1028
- *
1029
- * Should set `resolvedAt` and `resolvedBy` properties to `null` in your database and returns a promise
1030
- * that will be resolved when the operation is completed.
1031
- *
1032
- * @param data.channelId The ID of the document or context that the comment thread is removed from.
1033
- * @param data.threadId The ID of the thread to remove.
1034
- */
1035
- reopenCommentThread: (data: Omit<BaseCommentThread, 'isFromAdapter'>) => Promise<void>;
1036
- /**
1037
- * Called each time the user removes a comment thread.
1038
- *
1039
- * It should return a promise that resolves when the thread is removed.
1040
- *
1041
- * @param data.channelId The ID of the document or context that the comment thread is removed from.
1042
- * @param data.threadId The ID of the thread to remove.
1043
- */
1044
- removeCommentThread: (data: Omit<BaseCommentThread, 'isFromAdapter'>) => Promise<void>;
1045
- /**
1046
- * Called each time the user adds a new comment to a thread.
1047
- *
1048
- * It saves the comment data in the database and returns a promise
1049
- * that should get resolved when the save is completed.
1050
- *
1051
- * If the promise resolves with an object with the `createdAt` property, the
1052
- * comment property will be updated in the comment in the editor.
1053
- * This is to update the comment data with the server-side information.
1054
- *
1055
- * The `data` object does not expect the `authorId` property.
1056
- * For security reasons, the author of the comment should be set
1057
- * on the server side.
1058
- *
1059
- * The `data` object does not expect the `createdAt` property either.
1060
- * You should use the server-side time generator to ensure that all users
1061
- * see the same date.
1062
- *
1063
- * It is recommended to stringify the `data.attributes` value to JSON
1064
- * and to save it as a string in your database and then to parse the
1065
- * value from JSON when loading comments.
1066
- *
1067
- * The object which is passed as a parameter can contain the following properties:
1068
- * * channelId: string | symbol;
1069
- * * threadId: string;
1070
- * * commentId: string;
1071
- * * content: string;
1072
- * * attributes: Record<string, any>;
1073
- *
1074
- * The resolved data object should contain the following properties:
1075
- * * commentId: string;
1076
- * * createdAt: Date;
1077
- *
1078
- * @param data.channelId The ID of the document or context to which the comment is added.
1079
- * @param data.threadId The ID of the comment thread that the comment is added to.
1080
- * @param data.commentId The comment ID.
1081
- * @param data.content The comment content.
1082
- * @param data.attributes Comment custom attributes.
1083
- */
1084
- addComment: (data: Omit<BaseComment, 'isFromAdapter'> & BaseCommentData) => Promise<{
1085
- commentId: string;
1086
- createdAt: Date;
1087
- }>;
1088
- /**
1089
- * Called each time the user changes the existing comment.
1090
- *
1091
- * It updates the comment data in the database and returns a promise
1092
- * that will be resolved when the update is completed.
1093
- *
1094
- * Keep in mind that the `data` parameter only contains the
1095
- * properties of a comment that have changed.
1096
- *
1097
- * The object which is passed as a parameter can contain the following properties:
1098
- * * channelId: string | symbol;
1099
- * * threadId: string;
1100
- * * commentId: string;
1101
- * * content?: string;
1102
- * * attributes?: Record<string, any>;
1103
- *
1104
- * @param data.channelId The ID of the document or context where the comment is updated.
1105
- * @param data.threadId The ID of the comment thread where the comment is updated.
1106
- * @param data.commentId The ID of the comment to update.
1107
- * @param data.content The new content of the comment.
1108
- * @param data.attributes Custom comment attributes.
1109
- */
1110
- updateComment: (data: Omit<BaseComment, 'isFromAdapter'> & Partial<BaseCommentData>) => Promise<void>;
1111
- /**
1112
- * Called each time the user removes a comment from the thread.
1113
- *
1114
- * It removes the comment from the database and returns a promise
1115
- * that will be resolved when the removal is completed.
1116
- *
1117
- * @param data.channelId The ID of the document or context that the comment is removed from.
1118
- * @param data.threadId The ID of the comment thread that the comment is removed from.
1119
- * @param data.commentId The ID of the comment to remove.
1120
- */
1121
- removeComment: (data: Omit<BaseComment, 'isFromAdapter'>) => Promise<void>;
929
+ /**
930
+ * Called whenever a new comment thread is created.
931
+ *
932
+ * The object which is passed as a parameter can contain the following properties:
933
+ * * channelId: string | symbol;
934
+ * * threadId: string;
935
+ * * context?: {@link module:comments/comments/commentsrepository~CommentThreadContext CommentThreadContext};
936
+ * * comments?: Array<{@link module:comments/comments/commentsrepository~CommentDataJSON CommentDataJSON}>;
937
+ * * resolvedAt?: Date | null;
938
+ * * resolvedBy?: string | null;
939
+ * * attributes?: Record<string, any> | null;
940
+ *
941
+ * It should return a promise that resolves with the new comment thread data.
942
+ * The resolved data object should contain the following properties:
943
+ * * threadId: string;
944
+ * * comments: Array<\{ commentId: string; createdAt: Date; \}>;
945
+ */
946
+ addCommentThread: (data: Omit<CommentThreadData, "isFromAdapter"> & {
947
+ comments: Array<CommentDataJSON>;
948
+ }) => Promise<{
949
+ threadId: string;
950
+ comments: Array<{
951
+ commentId: string;
952
+ createdAt: Date;
953
+ }>;
954
+ }>;
955
+ /**
956
+ * Called when the editor needs the data for a comment thread.
957
+ *
958
+ * It should return a promise that resolves with the comment thread data.
959
+ * The resolved data object should contain the following properties:
960
+ * * threadId: string;
961
+ * * comments: Array<\{ commentId?: string; authorId: string; createdAt: Date; content: string; attributes: Record<string, any>; \}>;
962
+ * * resolvedAt?: Date | null;
963
+ * * resolvedBy?: string | null;
964
+ * * attributes: Record<string, unknown>;
965
+ *
966
+ * @param data.channelId The ID of the document or context to which the comment is added.
967
+ * @param data.threadId The ID of the comment thread that the comment is added to.
968
+ */
969
+ getCommentThread: (data: Omit<BaseCommentThread, "isFromAdapter">) => Promise<{
970
+ threadId: string;
971
+ comments: Array<CommentData>;
972
+ resolvedAt?: Date | null;
973
+ resolvedBy?: string | null;
974
+ attributes: Record<string, unknown>;
975
+ } | null>;
976
+ /**
977
+ * Called each time the user changes the existing comment thread.
978
+ *
979
+ * Keep in mind that for security reasons, the `authorId`, `createdAt`, `resolvedBy` and `resolvedAt` properties
980
+ * are not passed in the `updateCommentThread()` call and you should not set them as a result of this call.
981
+ *
982
+ * It updates the comment data in the database and returns a promise
983
+ * that will be resolved when the update is completed.
984
+ *
985
+ * The object which is passed as a parameter can contain the following properties:
986
+ * * channelId: string | symbol;
987
+ * * threadId: string;
988
+ * * context?: {@link module:comments/comments/commentsrepository~CommentThreadContext};
989
+ * * attributes?: Record<string, any> | null;
990
+ */
991
+ updateCommentThread: (data: Omit<UpdateCommentThreadEventData, "isFromAdapter">) => Promise<void>;
992
+ /**
993
+ * Called each time the user resolves a comment thread.
994
+ *
995
+ * Should set `resolvedAt` and `resolvedBy` properties in your database and should resolve with an object
996
+ * containing these two properties and returns a promise that will be resolved when the operation is completed.
997
+ *
998
+ * The resolved data object should contain the following properties:
999
+ * * threadId: string;
1000
+ * * resolvedAt: Date;
1001
+ * * resolvedBy: string;
1002
+ *
1003
+ * @param data.channelId The ID of the document or context that the comment thread is removed from.
1004
+ * @param data.threadId The ID of the thread to remove.
1005
+ */
1006
+ resolveCommentThread: (data: Omit<BaseCommentThread, "isFromAdapter">) => Promise<{
1007
+ threadId: string;
1008
+ resolvedAt: Date;
1009
+ resolvedBy: string;
1010
+ }>;
1011
+ /**
1012
+ * Called when the user reopens a resolved comment thread.
1013
+ *
1014
+ * Should set `resolvedAt` and `resolvedBy` properties to `null` in your database and returns a promise
1015
+ * that will be resolved when the operation is completed.
1016
+ *
1017
+ * @param data.channelId The ID of the document or context that the comment thread is removed from.
1018
+ * @param data.threadId The ID of the thread to remove.
1019
+ */
1020
+ reopenCommentThread: (data: Omit<BaseCommentThread, "isFromAdapter">) => Promise<void>;
1021
+ /**
1022
+ * Called each time the user removes a comment thread.
1023
+ *
1024
+ * It should return a promise that resolves when the thread is removed.
1025
+ *
1026
+ * @param data.channelId The ID of the document or context that the comment thread is removed from.
1027
+ * @param data.threadId The ID of the thread to remove.
1028
+ */
1029
+ removeCommentThread: (data: Omit<BaseCommentThread, "isFromAdapter">) => Promise<void>;
1030
+ /**
1031
+ * Called each time the user adds a new comment to a thread.
1032
+ *
1033
+ * It saves the comment data in the database and returns a promise
1034
+ * that should get resolved when the save is completed.
1035
+ *
1036
+ * If the promise resolves with an object with the `createdAt` property, the
1037
+ * comment property will be updated in the comment in the editor.
1038
+ * This is to update the comment data with the server-side information.
1039
+ *
1040
+ * The `data` object does not expect the `authorId` property.
1041
+ * For security reasons, the author of the comment should be set
1042
+ * on the server side.
1043
+ *
1044
+ * The `data` object does not expect the `createdAt` property either.
1045
+ * You should use the server-side time generator to ensure that all users
1046
+ * see the same date.
1047
+ *
1048
+ * It is recommended to stringify the `data.attributes` value to JSON
1049
+ * and to save it as a string in your database and then to parse the
1050
+ * value from JSON when loading comments.
1051
+ *
1052
+ * The object which is passed as a parameter can contain the following properties:
1053
+ * * channelId: string | symbol;
1054
+ * * threadId: string;
1055
+ * * commentId: string;
1056
+ * * content: string;
1057
+ * * attributes: Record<string, any>;
1058
+ *
1059
+ * The resolved data object should contain the following properties:
1060
+ * * commentId: string;
1061
+ * * createdAt: Date;
1062
+ *
1063
+ * @param data.channelId The ID of the document or context to which the comment is added.
1064
+ * @param data.threadId The ID of the comment thread that the comment is added to.
1065
+ * @param data.commentId The comment ID.
1066
+ * @param data.content The comment content.
1067
+ * @param data.attributes Comment custom attributes.
1068
+ */
1069
+ addComment: (data: Omit<BaseComment, "isFromAdapter"> & BaseCommentData) => Promise<{
1070
+ commentId: string;
1071
+ createdAt: Date;
1072
+ }>;
1073
+ /**
1074
+ * Called each time the user changes the existing comment.
1075
+ *
1076
+ * It updates the comment data in the database and returns a promise
1077
+ * that will be resolved when the update is completed.
1078
+ *
1079
+ * Keep in mind that the `data` parameter only contains the
1080
+ * properties of a comment that have changed.
1081
+ *
1082
+ * The object which is passed as a parameter can contain the following properties:
1083
+ * * channelId: string | symbol;
1084
+ * * threadId: string;
1085
+ * * commentId: string;
1086
+ * * content?: string;
1087
+ * * attributes?: Record<string, any>;
1088
+ *
1089
+ * @param data.channelId The ID of the document or context where the comment is updated.
1090
+ * @param data.threadId The ID of the comment thread where the comment is updated.
1091
+ * @param data.commentId The ID of the comment to update.
1092
+ * @param data.content The new content of the comment.
1093
+ * @param data.attributes Custom comment attributes.
1094
+ */
1095
+ updateComment: (data: Omit<BaseComment, "isFromAdapter"> & Partial<BaseCommentData>) => Promise<void>;
1096
+ /**
1097
+ * Called each time the user removes a comment from the thread.
1098
+ *
1099
+ * It removes the comment from the database and returns a promise
1100
+ * that will be resolved when the removal is completed.
1101
+ *
1102
+ * @param data.channelId The ID of the document or context that the comment is removed from.
1103
+ * @param data.threadId The ID of the comment thread that the comment is removed from.
1104
+ * @param data.commentId The ID of the comment to remove.
1105
+ */
1106
+ removeComment: (data: Omit<BaseComment, "isFromAdapter">) => Promise<void>;
1122
1107
  }
1123
1108
  export {};