@ckeditor/ckeditor5-comments 41.3.1 → 41.4.0

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

@@ -0,0 +1,71 @@
+/**
+ * @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/editorannotations
+ * @publicApi
+ */
+import { Plugin, type Editor } from 'ckeditor5/src/core.js';
+import Annotations from './annotations.js';
+import type Annotation from './annotation.js';
+import type AnnotationCollection from './annotationcollection.js';
+/**
+ * Integrates {@link module:comments/annotations/annotations~Annotations annotations} with the editor to provide proper behavior
+ * for annotations created through the editor features.
+ *
+ * *Note: The API of this class might change in the near future.*
+ *
+ * Collects all types of the annotations created through the editor features and their markers and decides which annotation is currently
+ * selected by the selection.
+ *
+ * Every editor plugin that adds an annotation should also
+ * {@link module:comments/annotations/editorannotations~EditorAnnotations#addSourceCollector register a callback}
+ * in which it will check whether given annotation should be marked as selected.
+ */
+export default class EditorAnnotations extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof Annotations];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "EditorAnnotations";
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Registers given annotation as an editor annotation, that is an annotation that is linked with a target inside the editor content.
+     */
+    registerAnnotation(annotation: Annotation): void;
+    hasDomSelection(): boolean;
+    /**
+     * Registers a callback that collects annotations and their markers.
+     */
+    addSourceCollector(callback: Function): void;
+    /**
+     * Finds all annotations selected by the editor selection and marks the most inner one as the active annotation.
+     */
+    refreshSelectedViews(): void;
+    /**
+     * Finds all annotations for selected markers in order from the most inner marker to the most outer marker.
+     *
+     * @param options.annotations The collection of annotations for given UI.
+     * @param options.activeAnnotation The given UI active annotation.
+     * It is used to determine the order if the selection contains the active annotation's marker.
+     */
+    getOrderedSelectedAnnotations({ activeAnnotation, annotations }: {
+        activeAnnotation: Annotation | null;
+        annotations: AnnotationCollection;
+    }): Array<Annotation>;
+}

package/dist/types/annotations/inlineannotations.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/inlineannotations
+ * @publicApi
+ */
+import { Plugin, type Editor } from 'ckeditor5/src/core.js';
+import AnnotationsUIs, { type AnnotationsUI } from './annotationsuis.js';
+import EditorAnnotations from './editorannotations.js';
+import { ContextualBalloon } from 'ckeditor5/src/ui.js';
+import './../../theme/annotation-inline.css';
+import type Annotation from './annotation.js';
+import type AnnotationCollection from './annotationcollection.js';
+/**
+ * The popup-style UI for displaying annotations next to editor target elements.
+ *
+ * It displays {@link module:comments/annotations/annotation~Annotation annotations} in the
+ * {@link module:ui/panel/balloon/contextualballoon~ContextualBalloon balloon} where the current
+ * {@link module:comments/annotations/inlineannotations~InlineAnnotations#activeAnnotation} is the displayed one.
+ *
+ * Note: this UI type works only with {@link module:core/editor/editor~Editor the Editor} and cannot be used in integrations where
+ * there is only {@link module:core/context~Context context} without any editor.
+ *
+ * This UI is intended for narrow screens.
+ *
+ * To activate this UI use one of the following:
+ *
+ * ```ts
+ * editor.plugins.get( 'AnnotationsUIs' ).switchTo( 'inline' );
+ * editor.plugins.get( 'AnnotationsUIs' ).activate( 'inline', filter );
+ * ```
+ *
+ * See {@link module:comments/annotations/annotationsuis~AnnotationsUIs}.
+ */
+export default class InlineAnnotations extends Plugin implements AnnotationsUI<Plugin> {
+    /**
+     * 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 `InlineAnnotations` is not
+     * {@link module:comments/annotations/inlineannotations~InlineAnnotations#attach attached}.
+     */
+    annotations: AnnotationCollection | null;
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof EditorAnnotations, typeof ContextualBalloon, typeof AnnotationsUIs];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "InlineAnnotations";
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * @inheritDoc
+     */
+    afterInit(): 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/annotations/narrowsidebar.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @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/narrowsidebar
+ * @publicApi
+ */
+import { ContextPlugin, Context, type Editor } from 'ckeditor5/src/core.js';
+import AnnotationsUIs, { type AnnotationsUI } from './annotationsuis.js';
+import Sidebar from './sidebar.js';
+import { BalloonPanelView, BodyCollection } from 'ckeditor5/src/ui.js';
+import '../../theme/sidebar-narrow.css';
+import type Annotation from './annotation.js';
+import type { default as AnnotationCollection } from './annotationcollection.js';
+/**
+ * The narrow sidebar UI for displaying annotations.
+ *
+ * Binds {@link module:comments/annotations/annotations~Annotations} plugin with
+ * {@link module:comments/annotations/sidebar~Sidebar} plugin to display annotations in the sidebar as
+ * {@link module:comments/annotations/view/annotationcounterbuttonview~AnnotationCounterButtonView small icons}.
+ *
+ * After selecting an annotation the {@link module:ui/panel/balloon/balloonpanelview~BalloonPanelView} with an
+ * {@link module:comments/annotations/view/annotationview~AnnotationView} appears attached to the sidebar item.
+ *
+ * This UI is intended for medium-sized viewports.
+ *
+ * To activate this UI use one of the following:
+ *
+ * ```ts
+ * editor.plugins.get( 'AnnotationsUIs' ).switchTo( 'narrowSidebar' );
+ * editor.plugins.get( 'AnnotationsUIs' ).activate( 'narrowSidebar', filter );
+ * ```
+ *
+ * See {@link module:comments/annotations/annotationsuis~AnnotationsUIs}.
+ */
+export default class NarrowSidebar extends ContextPlugin implements AnnotationsUI<ContextPlugin> {
+    /**
+     * An active annotation tracked by this UI.
+     */
+    activeAnnotation: Annotation | null;
+    bodyCollection: BodyCollection;
+    balloonPanelView: BalloonPanelView;
+    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 `NarrowSidebar` is not {@link module:comments/annotations/narrowsidebar~NarrowSidebar#attach attached}.
+     */
+    annotations: AnnotationCollection | null;
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof Sidebar, typeof AnnotationsUIs];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "NarrowSidebar";
+    /**
+     * @inheritDoc
+     */
+    constructor(context: Context | Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * @inheritDoc
+     */
+    attach(annotations: AnnotationCollection): void;
+    /**
+     * Sets the active annotation for this UI.
+     */
+    setActiveAnnotation(annotation: Annotation | null): void;
+    /**
+     * @inheritDoc
+     */
+    detach(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+}

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

@@ -0,0 +1,104 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module comments/annotations/sidebar
+ * @publicApi
+ */
+import { ContextPlugin, type Context, type Editor } from 'ckeditor5/src/core.js';
+import type { View } from 'ckeditor5/src/ui.js';
+import SidebarView from './view/sidebarview.js';
+import SidebarItemView from './view/sidebaritemview.js';
+import type Annotation from './annotation.js';
+/**
+ * Displays {@link module:comments/annotations/annotationcollection~AnnotationCollection annotations} inside a sidebar.
+ *
+ * `Sidebar` provides a {@link module:comments/annotations/view/sidebarview~SidebarView} which can be injected at any place on a website.
+ *
+ * It's main role is to display and correctly position annotation views added to the sidebar, accordingly to their target elements
+ * or `Rect`s.
+ *
+ * The following plugins use `Sidebar` to provide annotations UI:
+ *
+ * * {@link module:comments/annotations/widesidebar~WideSidebar}
+ * * {@link module:comments/annotations/narrowsidebar~NarrowSidebar}
+ *
+ * The sidebar plugin introduces {@link module:comments/annotations/view/sidebaritemview~SidebarItemView} which is a wrapper view for
+ * {@link module:comments/annotations/view/annotationview~AnnotationView}. It adds an interface needed for positioning views inside
+ * the sidebar.
+ *
+ * Structure of items:
+ *
+ *	                   |-> SidebarItemView -> AnnotationView -> added View
+ *	Sidebar#view#list -|-> SidebarItemView -> AnnotationView -> added View
+ *	                   |-> ...
+ */
+export default class Sidebar extends ContextPlugin {
+    /**
+     * Container element into which sidebar is injected (in the DOM).
+     *
+     * @observable
+     */
+    container: HTMLElement | null;
+    /**
+     * Sidebar view.
+     */
+    view: SidebarView;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "Sidebar";
+    /**
+     * @inheritDoc
+     */
+    constructor(context: Context | Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Sets a new sidebar container.
+     */
+    setContainer(container: HTMLElement): void;
+    /**
+     * Rearranges annotations when the annotation is removed.
+     */
+    rearrange({ removedAnnotation, previousAnnotation, nextAnnotation }: {
+        removedAnnotation: Annotation;
+        previousAnnotation: Annotation | null;
+        nextAnnotation: Annotation | null;
+    }): void;
+    /**
+     * Refreshes sidebar items when one of the annotations is activated.
+     *
+     * @param options.activatedAnnotation The activated annotation.
+     * @param options.blurredAnnotation The previously active annotation.
+     * @param options.disableAnimationOnActivatedAnnotation Disables animation on the activated annotation.
+     */
+    refresh({ blurredAnnotation, activatedAnnotation, disableAnimationOnActivatedAnnotation }: {
+        blurredAnnotation: Annotation | null;
+        activatedAnnotation: Annotation | null;
+        disableAnimationOnActivatedAnnotation?: boolean;
+    }): void;
+    /**
+     * Creates new {@link module:comments/annotations/view/sidebaritemview~SidebarItemView} and binds its
+     * position with {@link module:comments/annotations/view/annotationview~AnnotationView} target position.
+     *
+     * By default, annotation's view will be displayed in the sidebar. However, you can provide any other view
+     * to be displayed instead using `annotationToDisplay`. `annotation` will be then used only to gather data needed by `Sidebar`.
+     */
+    addAnnotation(annotation: Annotation, viewToDisplay?: View): SidebarItemView;
+    /**
+     * Returns sidebar item view that wraps given annotation view.
+     */
+    getSidebarItemView(annotation: Annotation): SidebarItemView | undefined;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+}

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

@@ -0,0 +1,33 @@
+/**
+ * @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/annotationcounterbuttonview
+ * @publicApi
+ */
+import { ButtonView, View } from 'ckeditor5/src/ui.js';
+import type { Locale } from 'ckeditor5/src/utils.js';
+/**
+ * A view used in the sidebar by {@link module:comments/annotations/narrowsidebar~NarrowSidebar}.
+ */
+export default class AnnotationCounterButtonView extends ButtonView {
+    /**
+     * @observable
+     */
+    isDirty: boolean;
+    /**
+     * @observable
+     */
+    number: number;
+    /**
+     * @observable
+     */
+    annotationType: string;
+    counterView: View;
+    constructor(locale: Locale);
+}

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;
+}