@ckeditor/ckeditor5-mention 0.0.0-nightly-20240603.0 → 0.0.0-nightly-20240604.0

package/README.md

@@ -15,12 +15,6 @@ 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, Collection, logWarning, env } from '@ckeditor/ckeditor5-utils/dist/index.js';
+import { CKEditorError, toMap, uid, Rect, keyCodes, logWarning, Collection, 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,69 +13,27 @@ const BRACKET_PAIRS = {
     '[': ']',
     '{': '}'
 };
-/**
- * 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 {
+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;
-    }
-    /**
-	 * @inheritDoc
-	 */ refresh() {
+     * @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;
@@ -95,47 +53,47 @@ const BRACKET_PAIRS = {
         }, 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());
@@ -162,23 +120,24 @@ const BRACKET_PAIRS = {
             }
         });
     }
+    /**
+     * @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;
+    }
 }
 
-/**
- * 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 {
+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;
@@ -382,56 +341,39 @@ const BRACKET_PAIRS = {
     return false;
 }
 
-/**
- * The mention ui view.
- */ class MentionsView extends ListView {
-    selected;
-    position;
+class MentionsView extends ListView {
     /**
-	 * @inheritDoc
-	 */ constructor(locale){
-        super(locale);
-        this.extendTemplate({
-            attributes: {
-                class: [
-                    'ck-mentions'
-                ],
-                tabindex: '-1'
-            }
-        });
-    }
-    /**
-	 * {@link #select Selects} the first item.
-	 */ selectFirst() {
+     * {@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;
@@ -455,34 +397,51 @@ const BRACKET_PAIRS = {
         }
     }
     /**
-	 * 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'
+            }
+        });
+    }
 }
 
-/**
- * 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 {
+class DomWrapperView extends View {
     /**
-	 * The DOM element for which wrapper was created.
-	 */ domElement;
+     * @inheritDoc
+     */ render() {
+        super.render();
+        this.element = this.domElement;
+    }
     /**
-	 * Creates an instance of {@link module:mention/ui/domwrapperview~DomWrapperView} class.
-	 *
-	 * Also see {@link #render}.
-	 */ constructor(locale, domElement){
+     * Focuses the DOM element.
+     */ focus() {
+        this.domElement.focus();
+    }
+    /**
+     * 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;
@@ -505,22 +464,9 @@ const BRACKET_PAIRS = {
             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;
@@ -543,49 +489,22 @@ const defaultCommitKeyCodes = [
     keyCodes.enter,
     keyCodes.tab
 ];
-/**
- * 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;
+class MentionUI extends Plugin {
     /**
-	 * @inheritDoc
-	 */ static get pluginName() {
+     * @inheritDoc
+     */ static get pluginName() {
         return 'MentionUI';
     }
     /**
-	 * @inheritDoc
-	 */ static get requires() {
+     * @inheritDoc
+     */ static get requires() {
         return [
             ContextualBalloon
         ];
     }
     /**
-	 * @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() {
+     * @inheritDoc
+     */ init() {
         const editor = this.editor;
         const commitKeys = editor.config.get('mention.commitKeys') || defaultCommitKeyCodes;
         const handledKeyCodes = defaultHandledKeyCodes.concat(commitKeys);
@@ -625,17 +544,17 @@ const defaultCommitKeyCodes = [
             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
                 });
             }
@@ -656,27 +575,27 @@ const defaultCommitKeyCodes = [
         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)=>{
@@ -723,14 +642,14 @@ const defaultCommitKeyCodes = [
         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;
@@ -769,18 +688,18 @@ const defaultCommitKeyCodes = [
                 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,
@@ -837,8 +756,8 @@ const defaultCommitKeyCodes = [
         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 );
@@ -867,8 +786,8 @@ const defaultCommitKeyCodes = [
         }
     }
     /**
-	 * 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.
@@ -885,8 +804,8 @@ const defaultCommitKeyCodes = [
         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' );
@@ -901,8 +820,8 @@ const defaultCommitKeyCodes = [
         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;
@@ -924,11 +843,11 @@ const defaultCommitKeyCodes = [
         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;
@@ -958,6 +877,18 @@ const defaultCommitKeyCodes = [
             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.
@@ -1154,22 +1085,18 @@ const defaultCommitKeyCodes = [
     return editor.model.markers.has('mention');
 }
 
-/**
- * The mention plugin.
- *
- * For a detailed overview, check the {@glink features/mentions Mention feature} guide.
- */ class Mention extends Plugin {
+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