@ckeditor/ckeditor5-comments 41.2.1 → 41.3.0-alpha.3

package/dist/types/annotations/view/annotationview.d.ts

@@ -0,0 +1,94 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module comments/annotations/view/annotationview
+ * @publicApi
+ */
+import { View, type ViewCollection } from 'ckeditor5/src/ui.js';
+import { FocusTracker, KeystrokeHandler, type Rect, type Locale } from 'ckeditor5/src/utils.js';
+import '../../../theme/annotation.css';
+/**
+ * A wrapping view for any view added to the `Annotations` plugin.
+ *
+ * It introduces functionalities that make the given view ready to be used as an annotation, such as focus tracking, height resizing,
+ * and other observable properties that help share current annotation state across different UIs.
+ */
+export default class AnnotationView extends View {
+    /**
+     * Tracks focus on the annotation view.
+     *
+     * Add a DOM element to this focus tracker to prevent blurring annotation view
+     * when the DOM element is focused.
+     */
+    readonly focusTracker: FocusTracker;
+    readonly id: string;
+    readonly keystrokes: KeystrokeHandler;
+    /**
+     * Target rectangle to which the annotation should be attached.
+     *
+     * @observable
+     */
+    targetRect: Rect | null;
+    /**
+     * Annotation view height.
+     *
+     * @observable
+     */
+    height: number;
+    /**
+     * Informs if an annotation is active.
+     *
+     * @observable
+     */
+    isActive: boolean;
+    /**
+     * Informs if there are unsaved changes in the annotation.
+     *
+     * @observable
+     */
+    isDirty: boolean;
+    /**
+     * The number of items in the annotation.
+     *
+     * @observable
+     */
+    length: number;
+    /**
+     * @observable
+     */
+    type: string;
+    element: HTMLElement;
+    /**
+     * Collection for content views.
+     */
+    content: ViewCollection;
+    /**
+     * The inner annotation view.
+     */
+    mainView: AnnotationMainView;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale: Locale, mainView: AnnotationMainView);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Focuses the annotation view.
+     */
+    focus(): void;
+}
+export interface AnnotationMainView extends View {
+    isActive: boolean;
+}

package/dist/types/annotations/view/sidebaritemview.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module comments/annotations/view/sidebaritemview
+ * @publicApi
+ */
+import { View, type ViewCollection } from 'ckeditor5/src/ui.js';
+import { type Locale } from 'ckeditor5/src/utils.js';
+/**
+ * A wrapper view that wraps given {@link module:ui/view~View} to display it as a {@link module:comments/annotations/sidebar~Sidebar} item.
+ */
+export default class SidebarItemView extends View {
+    element: HTMLElement;
+    /**
+     * The item top offset.
+     * Setting `0` as the initial value makes new items falling from heaven.
+     *
+     * @observable
+     */
+    top: number;
+    /**
+     * @observable
+     */
+    bottom: number;
+    /**
+     * @observable
+     */
+    height: number;
+    /**
+     * @observable
+     */
+    isAnimationDisabled: boolean;
+    /**
+     * A collection of content views.
+     */
+    content: ViewCollection;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale: Locale);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * Updates {@link #height the height property} according to the element's DOM height.
+     */
+    updateHeight(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+}

package/dist/types/annotations/view/sidebarview.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module comments/annotations/view/sidebarview
+ * @publicApi
+ */
+import { View, type ViewCollection } from 'ckeditor5/src/ui.js';
+import { type Locale } from 'ckeditor5/src/utils.js';
+import '../../../theme/sidebar.css';
+/**
+ * The sidebar view class that displays the collection of sidebar item views.
+ */
+export default class SidebarView extends View {
+    /**
+     * @observable
+     */
+    minHeight: number | null;
+    /**
+     * @observable
+     */
+    class: string;
+    /**
+     * A collection of sidebar item views.
+     */
+    list: ViewCollection;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale: Locale);
+}

package/dist/types/annotations/widesidebar.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module comments/annotations/widesidebar
+ * @publicApi
+ */
+import { ContextPlugin, Context, type Editor } from 'ckeditor5/src/core.js';
+import AnnotationsUIs, { type AnnotationsUI } from './annotationsuis.js';
+import Sidebar from './sidebar.js';
+import type Annotation from './annotation.js';
+import type { default as AnnotationCollection } from './annotationcollection.js';
+/**
+ * The wide sidebar UI for displaying annotations.
+ *
+ * In this implementation {@link module:comments/annotations/sidebar~Sidebar the sidebar} displays full
+ * {@link module:comments/annotations/view/annotationview~AnnotationView annotation views}.
+ *
+ * To activate this UI use one of the following:
+ *
+ * ```ts
+ * editor.plugins.get( 'AnnotationsUIs' ).switchTo( 'wideSidebar' );
+ * editor.plugins.get( 'AnnotationsUIs' ).activate( 'wideSidebar', filter );
+ * ```
+ *
+ * See {@link module:comments/annotations/annotationsuis~AnnotationsUIs}.
+ */
+export default class WideSidebar extends ContextPlugin implements AnnotationsUI<ContextPlugin> {
+    /**
+     * An active annotation tracked by this UI.
+     *
+     * @observable
+     */
+    activeAnnotation: Annotation | null;
+    isAttached: boolean;
+    /**
+     * A collection of annotations controlled by this UI.
+     *
+     * This property is readonly and should not be operated on directly. Use it only to read which annotations are added to this UI.
+     *
+     * It is set to `null` if `WideSidebar` is not {@link module:comments/annotations/widesidebar~WideSidebar#attach attached}.
+     */
+    annotations: AnnotationCollection | null;
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof Sidebar, typeof AnnotationsUIs];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "WideSidebar";
+    /**
+     * @inheritDoc
+     */
+    constructor(context: Context | Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Sets the active annotation for this UI.
+     */
+    setActiveAnnotation(annotation: Annotation | null): void;
+    /**
+     * @inheritDoc
+     */
+    attach(annotations: AnnotationCollection): void;
+    /**
+     * @inheritDoc
+     */
+    detach(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+}

package/dist/types/augmentation.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+import type { CommentsConfig, SidebarConfig, Annotations, AnnotationsUIs, EditorAnnotations, CommentsRepository, CommentsUI } from './index.js';
+declare module '@ckeditor/ckeditor5-core' {
+    interface EditorConfig {
+        /**
+         * The configuration of the comments feature.
+         * Introduced by the {@link module:comments/comments~Comments} feature.
+         *
+         * Read more in {@link module:comments/config~CommentsConfig}.
+         *
+         * ```ts
+         * ClassicEditor
+         * 	.create( {
+         * 		comments: ... // Locale editor configuration.
+         * 	} )
+         * 	.then( ... )
+         * 	.catch( ... );
+         * ```
+         *
+         * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
+         */
+        comments?: CommentsConfig;
+        /**
+         * The configuration of the sidebar feature.
+         * Introduced by the {@link module:comments/annotations/sidebar~Sidebar} feature.
+         */
+        sidebar?: SidebarConfig;
+        /**
+         * Enables {@link module:comments/commentsonly~CommentsOnly comments-only mode} when the editor initializes.
+         *
+         * ```ts
+         * ClassicEditor
+         * 	.create( {
+         * 		commentsOnly: true
+         * 	} )
+         * 	.then( ... )
+         * 	.catch( ... );
+         * ```
+         */
+        commentsOnly?: boolean;
+    }
+    interface PluginsMap {
+        [Annotations.pluginName]: Annotations;
+        [AnnotationsUIs.pluginName]: AnnotationsUIs;
+        [EditorAnnotations.pluginName]: EditorAnnotations;
+        [CommentsRepository.pluginName]: CommentsRepository;
+        [CommentsUI.pluginName]: CommentsUI;
+    }
+}

package/dist/types/comments/addcommentthreadcommand.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module comments/comments/addcommentthreadcommand
+ * @publicApi
+ */
+import { Command } from 'ckeditor5/src/core.js';
+/**
+ * Adds a new CommentMarker what automatically adds corresponding CommentThread to the CommentsEditing#threads collection.
+ * Note this command adds only a CommentThread draft, to make is public marker has to be changed to be managed using operation.
+ *
+ * ```ts
+ * // If `threadId` is not specified, `addCommentThread()` will generate a unique ID and use it:
+ * editor.execute( 'addCommentThread' );
+ *
+ * // If you want to specify the exact thread ID, pass it through the optional `threadId` configuration parameter.
+ * editor.execute( 'addCommentThread', { threadId: 'thread-1' } );
+ * ```
+ */
+export default class AddCommentThreadCommand extends Command {
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * @fires execute
+     * @param options Options for executed command.
+     * @param options.threadId Id of comment marker that will be added.
+     */
+    execute({ threadId }?: {
+        threadId?: string | undefined;
+    }): void;
+}

package/dist/types/comments/commentsarchive.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module comments/comments/commentsarchive
+ * @publicApi
+ */
+import { ContextPlugin, type Context, type Editor } from 'ckeditor5/src/core.js';
+import { Collection } from 'ckeditor5/src/utils.js';
+import CommentsRepository, { type CommentThread } from './commentsrepository.js';
+import Annotations from '../annotations/annotations.js';
+/**
+ * This plugin handles all operations on archived threads needed for the comments archive.
+ */
+export default class CommentsArchive extends ContextPlugin {
+    archivedThreads: Collection<CommentThread>;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "CommentsArchive";
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof CommentsRepository, typeof Annotations];
+    constructor(context: Context | Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+}

package/dist/types/comments/commentsarchiveui.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module comments/comments/commentsarchiveui
+ * @publicApi
+ */
+import '../../theme/commentsarchive.css';
+import { Plugin, type Editor } from 'ckeditor5/src/core.js';
+import { ViewCollection } from 'ckeditor5/src/ui.js';
+import CommentsArchiveView from './ui/view/commentsarchiveview.js';
+import CommentsArchive from './commentsarchive.js';
+import type AnnotationView from '../annotations/view/annotationview.js';
+/**
+ * Creates comments archive {@link module:ui/dropdown/dropdownview~DropdownView ui dropdown} and binds with
+ * archived comment thread annotation views.
+ */
+export default class CommentsArchiveUI extends Plugin {
+    commentsArchiveView: CommentsArchiveView | undefined;
+    annotationViews: ViewCollection<AnnotationView>;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "CommentsArchiveUI";
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof CommentsArchive];
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+}

package/dist/types/comments/commentsediting.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module comments/comments/commentsediting
+ */
+import { Plugin, type Editor } from 'ckeditor5/src/core.js';
+import type { Marker } from 'ckeditor5/src/engine.js';
+import CommentsRepository from './commentsrepository.js';
+import EditorAnnotations from '../annotations/editorannotations.js';
+import CommentsRestrictedEditingMode from './integrations/commentsrestrictededitingmode.js';
+import CommentsImportWord from './integrations/importword.js';
+import CommentsClipboard from './integrations/clipboard.js';
+import '../../theme/commentmarker.css';
+/**
+ * Plugin that keeps in sync comments in {@link module:comments/comments/commentsrepository~CommentsRepository} with
+ * {@link module:engine/model/markercollection~Marker comment markers}.
+ */
+export default class CommentsEditing extends Plugin {
+    /**
+     * If set to `true`, the plugin won't load comment thread for the new marker immediately after the marker is added to the editor.
+     * Instead, the plugin will wait until the flag will be set to `false` and then load missing comments.
+     *
+     * It's useful to hold fetching comments from the server when comments are used with real-time collaboration.
+     * When a user connects to an existing document, the operations from the history need to be applied one by one.
+     * An operation which added a new comment marker might be followed by an operation which removes that marker, so it's not
+     * necessary to make an additional request then.
+     *
+     * @observable
+     */
+    isThreadsLoadingPaused: boolean;
+    /**
+     * Name of the active comment marker.
+     *
+     * Markers conversion checks if comment should be marked as active and adds/removes additional css class during the conversion.
+     *
+     * @observable
+     */
+    activeMarker: string | null;
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof CommentsRepository, typeof EditorAnnotations, typeof CommentsRestrictedEditingMode, typeof CommentsImportWord, typeof CommentsClipboard];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "CommentsEditing";
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Returns `true` if there is at least one marker in the content that is related to a comment thread with given `threadId`.
+     *
+     * @param threadId Comment thread id.
+     */
+    hasMarkerForId(threadId: string): boolean;
+    /**
+     * Returns all markers that are related to the comment thread with the given `threadId`.
+     *
+     * @param threadId Comment thread id.
+     * @returns Array with all markers related to given comment thread.
+     */
+    getAllMarkersForId(threadId: string): Array<Marker>;
+    /**
+     * Scrolls editing view to the first thread marker.
+     *
+     * @param threadId Comment thread id.
+     */
+    scrollToThreadMarker(threadId: string): void;
+}