@ckeditor/ckeditor5-mention 41.4.2 → 42.0.0-alpha.0

package/README.md

@@ -15,6 +15,12 @@ Check out the demo in the [mentions (autocomplete) feature guide](https://ckedit
 
 See the [`@ckeditor/ckeditor5-mention` package](https://ckeditor.com/docs/ckeditor5/latest/api/mention.html) page in [CKEditor 5 documentation](https://ckeditor.com/docs/ckeditor5/latest/).
 
+## Installation
+
+```bash
+npm install ckeditor5
+```
+
 ## License
 
 Licensed under the terms of [GNU General Public License Version 2 or later](http://www.gnu.org/licenses/gpl.html). For full details about the license, please check the `LICENSE.md` file or [https://ckeditor.com/legal/ckeditor-oss-license](https://ckeditor.com/legal/ckeditor-oss-license).

package/dist/index.js

@@ -3,7 +3,7 @@
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
 import { Command, Plugin } from '@ckeditor/ckeditor5-core/dist/index.js';
-import { CKEditorError, toMap, uid, Rect, keyCodes, logWarning, Collection, env } from '@ckeditor/ckeditor5-utils/dist/index.js';
+import { CKEditorError, toMap, uid, Rect, keyCodes, Collection, logWarning, env } from '@ckeditor/ckeditor5-utils/dist/index.js';
 import { ListView, View, ListItemView, ContextualBalloon, clickOutsideHandler, ButtonView } from '@ckeditor/ckeditor5-ui/dist/index.js';
 import { TextWatcher } from '@ckeditor/ckeditor5-typing/dist/index.js';
 import { debounce } from 'lodash-es';
@@ -13,27 +13,69 @@ const BRACKET_PAIRS = {
     '[': ']',
     '{': '}'
 };
-class MentionCommand extends Command {
+/**
+ * The mention command.
+ *
+ * The command is registered by {@link module:mention/mentionediting~MentionEditing} as `'mention'`.
+ *
+ * To insert a mention into a range, execute the command and specify a mention object with a range to replace:
+ *
+ * ```ts
+ * const focus = editor.model.document.selection.focus;
+ *
+ * // It will replace one character before the selection focus with the '#1234' text
+ * // with the mention attribute filled with passed attributes.
+ * editor.execute( 'mention', {
+ * 	marker: '#',
+ * 	mention: {
+ * 		id: '#1234',
+ * 		name: 'Foo',
+ * 		title: 'Big Foo'
+ * 	},
+ * 	range: editor.model.createRange( focus.getShiftedBy( -1 ), focus )
+ * } );
+ *
+ * // It will replace one character before the selection focus with the 'The "Big Foo"' text
+ * // with the mention attribute filled with passed attributes.
+ * editor.execute( 'mention', {
+ * 	marker: '#',
+ * 	mention: {
+ * 		id: '#1234',
+ * 		name: 'Foo',
+ * 		title: 'Big Foo'
+ * 	},
+ * 	text: 'The "Big Foo"',
+ * 	range: editor.model.createRange( focus.getShiftedBy( -1 ), focus )
+ * } );
+ *	```
+ */ class MentionCommand extends Command {
     /**
-     * @inheritDoc
-     */ refresh() {
+	 * @inheritDoc
+	 */ constructor(editor){
+        super(editor);
+        // Since this command may pass range in execution parameters, it should be checked directly in execute block.
+        this._isEnabledBasedOnSelection = false;
+    }
+    /**
+	 * @inheritDoc
+	 */ refresh() {
         const model = this.editor.model;
         const doc = model.document;
         this.isEnabled = model.schema.checkAttributeInSelection(doc.selection, 'mention');
     }
     /**
-     * Executes the command.
-     *
-     * @param options Options for the executed command.
-     * @param options.mention The mention object to insert. When a string is passed, it will be used to create a plain
-     * object with the name attribute that equals the passed string.
-     * @param options.marker The marker character (e.g. `'@'`).
-     * @param options.text The text of the inserted mention. Defaults to the full mention string composed from `marker` and
-     * `mention` string or `mention.id` if an object is passed.
-     * @param options.range The range to replace.
-     * Note that the replaced range might be shorter than the inserted text with the mention attribute.
-     * @fires execute
-     */ execute(options) {
+	 * Executes the command.
+	 *
+	 * @param options Options for the executed command.
+	 * @param options.mention The mention object to insert. When a string is passed, it will be used to create a plain
+	 * object with the name attribute that equals the passed string.
+	 * @param options.marker The marker character (e.g. `'@'`).
+	 * @param options.text The text of the inserted mention. Defaults to the full mention string composed from `marker` and
+	 * `mention` string or `mention.id` if an object is passed.
+	 * @param options.range The range to replace.
+	 * Note that the replaced range might be shorter than the inserted text with the mention attribute.
+	 * @fires execute
+	 */ execute(options) {
         const model = this.editor.model;
         const document = model.document;
         const selection = document.selection;
@@ -53,47 +95,47 @@ class MentionCommand extends Command {
         }, mentionData);
         if (options.marker.length != 1) {
             /**
-             * The marker must be a single character.
-             *
-             * Correct markers: `'@'`, `'#'`.
-             *
-             * Incorrect markers: `'@@'`, `'[@'`.
-             *
-             * See {@link module:mention/mentionconfig~MentionConfig}.
-             *
-             * @error mentioncommand-incorrect-marker
-             */ throw new CKEditorError('mentioncommand-incorrect-marker', this);
+			 * The marker must be a single character.
+			 *
+			 * Correct markers: `'@'`, `'#'`.
+			 *
+			 * Incorrect markers: `'@@'`, `'[@'`.
+			 *
+			 * See {@link module:mention/mentionconfig~MentionConfig}.
+			 *
+			 * @error mentioncommand-incorrect-marker
+			 */ throw new CKEditorError('mentioncommand-incorrect-marker', this);
         }
         if (mentionID.charAt(0) != options.marker) {
             /**
-             * The feed item ID must start with the marker character.
-             *
-             * Correct mention feed setting:
-             *
-             * ```ts
-             * mentions: [
-             * 	{
-             * 		marker: '@',
-             * 		feed: [ '@Ann', '@Barney', ... ]
-             * 	}
-             * ]
-             * ```
-             *
-             * Incorrect mention feed setting:
-             *
-             * ```ts
-             * mentions: [
-             * 	{
-             * 		marker: '@',
-             * 		feed: [ 'Ann', 'Barney', ... ]
-             * 	}
-             * ]
-             * ```
-             *
-             * See {@link module:mention/mentionconfig~MentionConfig}.
-             *
-             * @error mentioncommand-incorrect-id
-             */ throw new CKEditorError('mentioncommand-incorrect-id', this);
+			 * The feed item ID must start with the marker character.
+			 *
+			 * Correct mention feed setting:
+			 *
+			 * ```ts
+			 * mentions: [
+			 * 	{
+			 * 		marker: '@',
+			 * 		feed: [ '@Ann', '@Barney', ... ]
+			 * 	}
+			 * ]
+			 * ```
+			 *
+			 * Incorrect mention feed setting:
+			 *
+			 * ```ts
+			 * mentions: [
+			 * 	{
+			 * 		marker: '@',
+			 * 		feed: [ 'Ann', 'Barney', ... ]
+			 * 	}
+			 * ]
+			 * ```
+			 *
+			 * See {@link module:mention/mentionconfig~MentionConfig}.
+			 *
+			 * @error mentioncommand-incorrect-id
+			 */ throw new CKEditorError('mentioncommand-incorrect-id', this);
         }
         model.change((writer)=>{
             const currentAttributes = toMap(selection.getAttributes());
@@ -120,24 +162,23 @@ class MentionCommand extends Command {
             }
         });
     }
-    /**
-     * @inheritDoc
-     */ constructor(editor){
-        super(editor);
-        // Since this command may pass range in execution parameters, it should be checked directly in execute block.
-        this._isEnabledBasedOnSelection = false;
-    }
 }
 
-class MentionEditing extends Plugin {
+/**
+ * The mention editing feature.
+ *
+ * It introduces the {@link module:mention/mentioncommand~MentionCommand command} and the `mention`
+ * attribute in the {@link module:engine/model/model~Model model} which renders in the {@link module:engine/view/view view}
+ * as a `<span class="mention" data-mention="@mention">`.
+ */ class MentionEditing extends Plugin {
     /**
-     * @inheritDoc
-     */ static get pluginName() {
+	 * @inheritDoc
+	 */ static get pluginName() {
         return 'MentionEditing';
     }
     /**
-     * @inheritDoc
-     */ init() {
+	 * @inheritDoc
+	 */ init() {
         const editor = this.editor;
         const model = editor.model;
         const doc = model.document;
@@ -341,39 +382,56 @@ class MentionEditing extends Plugin {
     return false;
 }
 
-class MentionsView extends ListView {
+/**
+ * The mention ui view.
+ */ class MentionsView extends ListView {
+    selected;
+    position;
     /**
-     * {@link #select Selects} the first item.
-     */ selectFirst() {
+	 * @inheritDoc
+	 */ constructor(locale){
+        super(locale);
+        this.extendTemplate({
+            attributes: {
+                class: [
+                    'ck-mentions'
+                ],
+                tabindex: '-1'
+            }
+        });
+    }
+    /**
+	 * {@link #select Selects} the first item.
+	 */ selectFirst() {
         this.select(0);
     }
     /**
-     * Selects next item to the currently {@link #select selected}.
-     *
-     * If the last item is already selected, it will select the first item.
-     */ selectNext() {
+	 * Selects next item to the currently {@link #select selected}.
+	 *
+	 * If the last item is already selected, it will select the first item.
+	 */ selectNext() {
         const item = this.selected;
         const index = this.items.getIndex(item);
         this.select(index + 1);
     }
     /**
-     * Selects previous item to the currently {@link #select selected}.
-     *
-     * If the first item is already selected, it will select the last item.
-     */ selectPrevious() {
+	 * Selects previous item to the currently {@link #select selected}.
+	 *
+	 * If the first item is already selected, it will select the last item.
+	 */ selectPrevious() {
         const item = this.selected;
         const index = this.items.getIndex(item);
         this.select(index - 1);
     }
     /**
-     * Marks item at a given index as selected.
-     *
-     * Handles selection cycling when passed index is out of bounds:
-     * - if the index is lower than 0, it will select the last item,
-     * - if the index is higher than the last item index, it will select the first item.
-     *
-     * @param index Index of an item to be marked as selected.
-     */ select(index) {
+	 * Marks item at a given index as selected.
+	 *
+	 * Handles selection cycling when passed index is out of bounds:
+	 * - if the index is lower than 0, it will select the last item,
+	 * - if the index is higher than the last item index, it will select the first item.
+	 *
+	 * @param index Index of an item to be marked as selected.
+	 */ select(index) {
         let indexToGet = 0;
         if (index > 0 && index < this.items.length) {
             indexToGet = index;
@@ -397,51 +455,34 @@ class MentionsView extends ListView {
         }
     }
     /**
-     * Triggers the `execute` event on the {@link #select selected} item.
-     */ executeSelected() {
+	 * Triggers the `execute` event on the {@link #select selected} item.
+	 */ executeSelected() {
         this.selected.fire('execute');
     }
     /**
-     * Checks if an item is visible in the scrollable area.
-     *
-     * The item is considered visible when:
-     * - its top boundary is inside the scrollable rect
-     * - its bottom boundary is inside the scrollable rect (the whole item must be visible)
-     */ _isItemVisibleInScrolledArea(item) {
+	 * Checks if an item is visible in the scrollable area.
+	 *
+	 * The item is considered visible when:
+	 * - its top boundary is inside the scrollable rect
+	 * - its bottom boundary is inside the scrollable rect (the whole item must be visible)
+	 */ _isItemVisibleInScrolledArea(item) {
         return new Rect(this.element).contains(new Rect(item.element));
     }
-    /**
-     * @inheritDoc
-     */ constructor(locale){
-        super(locale);
-        this.extendTemplate({
-            attributes: {
-                class: [
-                    'ck-mentions'
-                ],
-                tabindex: '-1'
-            }
-        });
-    }
 }
 
-class DomWrapperView extends View {
-    /**
-     * @inheritDoc
-     */ render() {
-        super.render();
-        this.element = this.domElement;
-    }
+/**
+ * This class wraps DOM element as a CKEditor5 UI View.
+ *
+ * It allows to render any DOM element and use it in mentions list.
+ */ class DomWrapperView extends View {
     /**
-     * Focuses the DOM element.
-     */ focus() {
-        this.domElement.focus();
-    }
+	 * The DOM element for which wrapper was created.
+	 */ domElement;
     /**
-     * Creates an instance of {@link module:mention/ui/domwrapperview~DomWrapperView} class.
-     *
-     * Also see {@link #render}.
-     */ constructor(locale, domElement){
+	 * Creates an instance of {@link module:mention/ui/domwrapperview~DomWrapperView} class.
+	 *
+	 * Also see {@link #render}.
+	 */ constructor(locale, domElement){
         super(locale);
         // Disable template rendering on this view.
         this.template = undefined;
@@ -464,9 +505,22 @@ class DomWrapperView extends View {
             this.fire('execute');
         });
     }
+    /**
+	 * @inheritDoc
+	 */ render() {
+        super.render();
+        this.element = this.domElement;
+    }
+    /**
+	 * Focuses the DOM element.
+	 */ focus() {
+        this.domElement.focus();
+    }
 }
 
 class MentionListItemView extends ListItemView {
+    item;
+    marker;
     highlight() {
         const child = this.children.first;
         child.isOn = true;
@@ -489,22 +543,49 @@ const defaultCommitKeyCodes = [
     keyCodes.enter,
     keyCodes.tab
 ];
-class MentionUI extends Plugin {
+/**
+ * The mention UI feature.
+ */ class MentionUI extends Plugin {
+    /**
+	 * The mention view.
+	 */ _mentionsView;
+    /**
+	 * Stores mention feeds configurations.
+	 */ _mentionsConfigurations;
+    /**
+	 * The contextual balloon plugin instance.
+	 */ _balloon;
+    _items = new Collection();
+    _lastRequested;
+    /**
+	 * Debounced feed requester. It uses `lodash#debounce` method to delay function call.
+	 */ _requestFeedDebounced;
     /**
-     * @inheritDoc
-     */ static get pluginName() {
+	 * @inheritDoc
+	 */ static get pluginName() {
         return 'MentionUI';
     }
     /**
-     * @inheritDoc
-     */ static get requires() {
+	 * @inheritDoc
+	 */ static get requires() {
         return [
             ContextualBalloon
         ];
     }
     /**
-     * @inheritDoc
-     */ init() {
+	 * @inheritDoc
+	 */ constructor(editor){
+        super(editor);
+        this._mentionsView = this._createMentionView();
+        this._mentionsConfigurations = new Map();
+        this._requestFeedDebounced = debounce(this._requestFeed, 100);
+        editor.config.define('mention', {
+            feeds: []
+        });
+    }
+    /**
+	 * @inheritDoc
+	 */ init() {
         const editor = this.editor;
         const commitKeys = editor.config.get('mention.commitKeys') || defaultCommitKeyCodes;
         const handledKeyCodes = defaultHandledKeyCodes.concat(commitKeys);
@@ -544,17 +625,17 @@ class MentionUI extends Plugin {
             const { feed, marker, dropdownLimit } = mentionDescription;
             if (!isValidMentionMarker(marker)) {
                 /**
-                 * The marker must be a single character.
-                 *
-                 * Correct markers: `'@'`, `'#'`.
-                 *
-                 * Incorrect markers: `'$$'`, `'[@'`.
-                 *
-                 * See {@link module:mention/mentionconfig~MentionConfig}.
-                 *
-                 * @error mentionconfig-incorrect-marker
-                 * @param marker Configured marker
-                 */ throw new CKEditorError('mentionconfig-incorrect-marker', null, {
+				 * The marker must be a single character.
+				 *
+				 * Correct markers: `'@'`, `'#'`.
+				 *
+				 * Incorrect markers: `'$$'`, `'[@'`.
+				 *
+				 * See {@link module:mention/mentionconfig~MentionConfig}.
+				 *
+				 * @error mentionconfig-incorrect-marker
+				 * @param marker Configured marker
+				 */ throw new CKEditorError('mentionconfig-incorrect-marker', null, {
                     marker
                 });
             }
@@ -575,27 +656,27 @@ class MentionUI extends Plugin {
         this.on('requestFeed:response', (evt, data)=>this._handleFeedResponse(data));
         this.on('requestFeed:error', ()=>this._hideUIAndRemoveMarker());
         /**
-         * Checks if a given key code is handled by the mention UI.
-         */ function isHandledKey(keyCode) {
+		 * Checks if a given key code is handled by the mention UI.
+		 */ function isHandledKey(keyCode) {
             return handledKeyCodes.includes(keyCode);
         }
     }
     /**
-     * @inheritDoc
-     */ destroy() {
+	 * @inheritDoc
+	 */ destroy() {
         super.destroy();
         // Destroy created UI components as they are not automatically destroyed (see ckeditor5#1341).
         this._mentionsView.destroy();
     }
     /**
-     * Returns true when {@link #_mentionsView} is in the {@link module:ui/panel/balloon/contextualballoon~ContextualBalloon} and it is
-     * currently visible.
-     */ get _isUIVisible() {
+	 * Returns true when {@link #_mentionsView} is in the {@link module:ui/panel/balloon/contextualballoon~ContextualBalloon} and it is
+	 * currently visible.
+	 */ get _isUIVisible() {
         return this._balloon.visibleView === this._mentionsView;
     }
     /**
-     * Creates the {@link #_mentionsView}.
-     */ _createMentionView() {
+	 * Creates the {@link #_mentionsView}.
+	 */ _createMentionView() {
         const locale = this.editor.locale;
         const mentionsView = new MentionsView(locale);
         mentionsView.items.bindTo(this._items).using((data)=>{
@@ -642,14 +723,14 @@ class MentionUI extends Plugin {
         return mentionsView;
     }
     /**
-     * Returns item renderer for the marker.
-     */ _getItemRenderer(marker) {
+	 * Returns item renderer for the marker.
+	 */ _getItemRenderer(marker) {
         const { itemRenderer } = this._mentionsConfigurations.get(marker);
         return itemRenderer;
     }
     /**
-     * Requests a feed from a configured callbacks.
-     */ _requestFeed(marker, feedText) {
+	 * Requests a feed from a configured callbacks.
+	 */ _requestFeed(marker, feedText) {
         // @if CK_DEBUG_MENTION // console.log( '%c[Feed]%c Requesting for', 'color: blue', 'color: black', `"${ feedText }"` );
         // Store the last requested feed - it is used to discard any out-of order requests.
         this._lastRequested = feedText;
@@ -688,18 +769,18 @@ class MentionUI extends Plugin {
                 error
             });
             /**
-             * The callback used for obtaining mention autocomplete feed thrown and error and the mention UI was hidden or
-             * not displayed at all.
-             *
-             * @error mention-feed-callback-error
-             */ logWarning('mention-feed-callback-error', {
+				 * The callback used for obtaining mention autocomplete feed thrown and error and the mention UI was hidden or
+				 * not displayed at all.
+				 *
+				 * @error mention-feed-callback-error
+				 */ logWarning('mention-feed-callback-error', {
                 marker
             });
         });
     }
     /**
-     * Registers a text watcher for the marker.
-     */ _setupTextWatcher(feeds) {
+	 * Registers a text watcher for the marker.
+	 */ _setupTextWatcher(feeds) {
         const editor = this.editor;
         const feedsWithPattern = feeds.map((feed)=>({
                 ...feed,
@@ -756,8 +837,8 @@ class MentionUI extends Plugin {
         return watcher;
     }
     /**
-     * Handles the feed response event data.
-     */ _handleFeedResponse(data) {
+	 * Handles the feed response event data.
+	 */ _handleFeedResponse(data) {
         const { feed, marker } = data;
         // eslint-disable-next-line max-len
         // @if CK_DEBUG_MENTION // console.log( `%c[Feed]%c Response for "${ data.feedText }" (${ feed.length })`, 'color: blue', 'color: black', feed );
@@ -786,8 +867,8 @@ class MentionUI extends Plugin {
         }
     }
     /**
-     * Shows the mentions balloon. If the panel is already visible, it will reposition it.
-     */ _showOrUpdateUI(markerMarker) {
+	 * Shows the mentions balloon. If the panel is already visible, it will reposition it.
+	 */ _showOrUpdateUI(markerMarker) {
         if (this._isUIVisible) {
             // @if CK_DEBUG_MENTION // console.log( '%c[UI]%c Updating position.', 'color: green', 'color: black' );
             // Update balloon position as the mention list view may change its size.
@@ -804,8 +885,8 @@ class MentionUI extends Plugin {
         this._mentionsView.selectFirst();
     }
     /**
-     * Hides the mentions balloon and removes the 'mention' marker from the markers collection.
-     */ _hideUIAndRemoveMarker() {
+	 * Hides the mentions balloon and removes the 'mention' marker from the markers collection.
+	 */ _hideUIAndRemoveMarker() {
         // Remove the mention view from balloon before removing marker - it is used by balloon position target().
         if (this._balloon.hasView(this._mentionsView)) {
             // @if CK_DEBUG_MENTION // console.log( '%c[UI]%c Hiding the UI.', 'color: green', 'color: black' );
@@ -820,8 +901,8 @@ class MentionUI extends Plugin {
         this._mentionsView.position = undefined;
     }
     /**
-     * Renders a single item in the autocomplete list.
-     */ _renderItem(item, marker) {
+	 * Renders a single item in the autocomplete list.
+	 */ _renderItem(item, marker) {
         const editor = this.editor;
         let view;
         let label = item.id;
@@ -843,11 +924,11 @@ class MentionUI extends Plugin {
         return view;
     }
     /**
-     * Creates a position options object used to position the balloon panel.
-     *
-     * @param mentionMarker
-     * @param preferredPosition The name of the last matched position name.
-     */ _getBalloonPanelPositionData(mentionMarker, preferredPosition) {
+	 * Creates a position options object used to position the balloon panel.
+	 *
+	 * @param mentionMarker
+	 * @param preferredPosition The name of the last matched position name.
+	 */ _getBalloonPanelPositionData(mentionMarker, preferredPosition) {
         const editor = this.editor;
         const editing = editor.editing;
         const domConverter = editing.view.domConverter;
@@ -877,18 +958,6 @@ class MentionUI extends Plugin {
             positions: getBalloonPanelPositions(preferredPosition, uiLanguageDirection)
         };
     }
-    /**
-     * @inheritDoc
-     */ constructor(editor){
-        super(editor);
-        this._items = new Collection();
-        this._mentionsView = this._createMentionView();
-        this._mentionsConfigurations = new Map();
-        this._requestFeedDebounced = debounce(this._requestFeed, 100);
-        editor.config.define('mention', {
-            feeds: []
-        });
-    }
 }
 /**
  * Returns the balloon positions data callbacks.
@@ -1085,18 +1154,22 @@ class MentionUI extends Plugin {
     return editor.model.markers.has('mention');
 }
 
-class Mention extends Plugin {
+/**
+ * The mention plugin.
+ *
+ * For a detailed overview, check the {@glink features/mentions Mention feature} guide.
+ */ class Mention extends Plugin {
     toMentionAttribute(viewElement, data) {
         return _toMentionAttribute(viewElement, data);
     }
     /**
-     * @inheritDoc
-     */ static get pluginName() {
+	 * @inheritDoc
+	 */ static get pluginName() {
         return 'Mention';
     }
     /**
-     * @inheritDoc
-     */ static get requires() {
+	 * @inheritDoc
+	 */ static get requires() {
         return [
             MentionEditing,
             MentionUI