@ckeditor/ckeditor5-mention 41.2.0 → 41.3.0-alpha.1

package/dist/types/mention.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @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 mention/mention
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import type { Element } from 'ckeditor5/src/engine.js';
+import MentionEditing from './mentionediting.js';
+import MentionUI from './mentionui.js';
+import '../theme/mention.css';
+/**
+ * The mention plugin.
+ *
+ * For a detailed overview, check the {@glink features/mentions Mention feature} guide.
+ */
+export default class Mention extends Plugin {
+    /**
+     * Creates a mention attribute value from the provided view element and additional data.
+     *
+     * ```ts
+     * editor.plugins.get( 'Mention' ).toMentionAttribute( viewElement, { userId: '1234' } );
+     *
+     * // For a view element: <span data-mention="@joe">@John Doe</span>
+     * // it will return:
+     * // { id: '@joe', userId: '1234', uid: '7a7bc7...', _text: '@John Doe' }
+     * ```
+     *
+     * @param data Additional data to be stored in the mention attribute.
+     */
+    toMentionAttribute<MentionData extends Record<string, unknown>>(viewElement: Element, data: MentionData): (MentionAttribute & MentionData) | undefined;
+    /**
+     * Creates a mention attribute value from the provided view element.
+     *
+     * ```ts
+     * editor.plugins.get( 'Mention' ).toMentionAttribute( viewElement );
+     *
+     * // For a view element: <span data-mention="@joe">@John Doe</span>
+     * // it will return:
+     * // { id: '@joe', uid: '7a7bc7...', _text: '@John Doe' }
+     * ```
+     */
+    toMentionAttribute(viewElement: Element): MentionAttribute | undefined;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "Mention";
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof MentionEditing, typeof MentionUI];
+}
+/**
+ * Represents a mention in the model.
+ *
+ * See {@link module:mention/mention~Mention#toMentionAttribute `Mention#toMentionAttribute()`}.
+ */
+export type MentionAttribute = {
+    /**
+     * The ID of a mention. It identifies the mention item in the mention feed. There can be multiple mentions
+     * in the document with the same ID (e.g. the same hashtag being mentioned).
+     */
+    id: string;
+    /**
+     * A unique ID of this mention instance. Should be passed as an `option.id` when using
+     * {@link module:engine/view/downcastwriter~DowncastWriter#createAttributeElement writer.createAttributeElement()}.
+     */
+    uid: string;
+    /**
+     * Helper property that stores the text of the inserted mention. Used for detecting a broken mention
+     * in the editing area.
+     *
+     * @internal
+     */
+    _text: string;
+};

package/dist/types/mentioncommand.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @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 mention/mentioncommand
+ */
+import { Command, type Editor } from 'ckeditor5/src/core.js';
+import type { Range } from 'ckeditor5/src/engine.js';
+/**
+ * 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 )
+ * } );
+ *	```
+ */
+export default class MentionCommand extends Command {
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * 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: {
+        mention: string | {
+            id: string;
+            [key: string]: unknown;
+        };
+        marker: string;
+        text?: string;
+        range?: Range;
+    }): void;
+}

package/dist/types/mentionconfig.d.ts

@@ -0,0 +1,265 @@
+/**
+ * @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 mention/mentionconfig
+ */
+/**
+ * The configuration of the mention feature.
+ *
+ * Read more about {@glink features/mentions#configuration configuring the mention feature}.
+ *
+ * ```ts
+ * ClassicEditor
+ * 	.create( editorElement, {
+ * 		mention: ... // Mention feature options.
+ * 	} )
+ * 	.then( ... )
+ * 	.catch( ... );
+ * ```
+ *
+ * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
+ */
+export interface MentionConfig {
+    /**
+     * The list of mention feeds supported by the editor.
+     *
+     * ```ts
+     * ClassicEditor
+     * 	.create( editorElement, {
+     * 		plugins: [ Mention, ... ],
+     * 		mention: {
+     * 			feeds: [
+     * 				{
+     * 					marker: '@',
+     * 					feed: [ '@Barney', '@Lily', '@Marshall', '@Robin', '@Ted' ]
+     * 				},
+     * 				...
+     * 			]
+     * 		}
+     * 	} )
+     * 	.then( ... )
+     * 	.catch( ... );
+     * ```
+     *
+     * You can provide many mention feeds but they must use different `marker`s.
+     * For example, you can use `'@'` to autocomplete people and `'#'` to autocomplete tags.
+     */
+    feeds: Array<MentionFeed>;
+    /**
+     * The configuration of the custom commit keys supported by the editor.
+     *
+     * ```ts
+     * ClassicEditor
+     * 	.create( editorElement, {
+     * 		plugins: [ Mention, ... ],
+     * 		mention: {
+     * 			// [ Enter, Space ]
+     * 			commitKeys: [ 13, 32 ]
+     * 			feeds: [
+     * 				{ ... }
+     * 				...
+     * 			]
+     * 		}
+     * 	} )
+     * 	.then( ... )
+     * 	.catch( ... );
+     * ```
+     *
+     * Custom commit keys configuration allows you to customize how users will confirm the selection of mentions from the dropdown list.
+     * You can add as many mention commit keys as you need. For instance, in the snippet above new mentions will be committed by pressing
+     * either <kbd>Enter</kbd> or <kbd>Space</kbd> (13 and 32 key codes respectively).
+     *
+     * @default [ 13, 9 ] // [ Enter, Tab ]
+     */
+    commitKeys?: Array<number>;
+    /**
+     * The configuration of the custom number of visible mentions.
+     *
+     * Customizing the number of visible mentions allows you to specify how many available elements will the users be able to see
+     * in the dropdown list. You can specify any number you see fit. For example, in the snippets below you will find the
+     * dropdownLimit set to `20` and `Infinity` (the latter will result in showing all available mentions).
+     *
+     * ```ts
+     * ClassicEditor
+     * 	.create( editorElement, {
+     * 		plugins: [ Mention, ... ],
+     * 		mention: {
+     * 			dropdownLimit: 20,
+     * 			feeds: [
+     * 				{ ... }
+     * 				...
+     * 			]
+     * 		}
+     * 	} )
+     * 	.then( ... )
+     * 	.catch( ... );
+     *
+     * ClassicEditor
+     * 	.create( editorElement, {
+     * 		plugins: [ Mention, ... ],
+     * 		mention: {
+     * 			dropdownLimit: Infinity,
+     * 			feeds: [
+     * 				{ ... }
+     * 				...
+     * 			]
+     * 		}
+     * 	} )
+     * 	.then( ... )
+     * 	.catch( ... );
+     * ```
+     *
+     * @default 10
+     */
+    dropdownLimit?: number;
+}
+/**
+ * The mention feed descriptor. Used in {@link module:mention/mentionconfig~MentionConfig `config.mention`}.
+ *
+ * See {@link module:mention/mentionconfig~MentionConfig} to learn more.
+ *
+ * ```ts
+ * // Static configuration.
+ * const mentionFeedPeople = {
+ * 	marker: '@',
+ * 	feed: [ '@Alice', '@Bob', ... ],
+ * 	minimumCharacters: 2
+ * };
+ *
+ * // Simple synchronous callback.
+ * const mentionFeedTags = {
+ * 	marker: '#',
+ * 	feed: ( searchString: string ) => {
+ * 		return tags
+ * 			// Filter the tags list.
+ * 			.filter( tag => {
+ * 				return tag.toLowerCase().includes( queryText.toLowerCase() );
+ * 			} )
+ * 	}
+ * };
+ *
+ * const tags = [ 'wysiwyg', 'rte', 'rich-text-edior', 'collaboration', 'real-time', ... ];
+ *
+ * // Asynchronous callback.
+ * const mentionFeedPlaceholders = {
+ * 	marker: '$',
+ * 	feed: ( searchString: string ) => {
+ * 		return getMatchingPlaceholders( searchString );
+ * 	}
+ * };
+ *
+ * function getMatchingPlaceholders( searchString: string ) {
+ * 	return new Promise<Array<MentionFeedItem>>( resolve => {
+ * 		doSomeXHRQuery( result => {
+ * 			// console.log( result );
+ * 			// -> [ '$name', '$surname', '$postal', ... ]
+ *
+ * 			resolve( result );
+ * 		} );
+ * 	} );
+ * }
+ * ```
+ */
+export interface MentionFeed {
+    /**
+     * The character which triggers autocompletion for mention. It must be a single character.
+     */
+    marker: string;
+    /**
+     * Autocomplete items. Provide an array for
+     * a static configuration (the mention feature will show matching items automatically) or a function which returns an array of
+     * matching items (directly, or via a promise). If a function is passed, it is executed in the context of the editor instance.
+     */
+    feed: Array<MentionFeedItem> | FeedCallback;
+    /**
+     * Specifies after how many characters the autocomplete panel should be shown.
+     *
+     * @default 0
+     */
+    minimumCharacters?: number;
+    /**
+     * A function that renders a {@link module:mention/mentionconfig~MentionFeedItem}
+     * to the autocomplete panel.
+     */
+    itemRenderer?: ItemRenderer;
+    /**
+     * Specify how many available elements per feeds will the users be able to see in the dropdown list.
+     * If it not set, limit is inherited from {@link module:mention/mentionconfig~MentionConfig#dropdownLimit MentionConfig}.
+     */
+    dropdownLimit?: number;
+}
+/**
+ * Function that renders an array of {@link module:mention/mentionconfig~MentionFeedItem} based on string input.
+ */
+export type FeedCallback = (searchString: string) => Array<MentionFeedItem> | Promise<Array<MentionFeedItem>>;
+/**
+ * Function that takes renders a {@link module:mention/mentionconfig~MentionFeedObjectItem} as HTMLElement.
+ */
+export type ItemRenderer = (item: MentionFeedObjectItem) => HTMLElement | string;
+/**
+ * The mention feed item. It may be defined as a string or a plain object.
+ *
+ * When defining a feed item as a plain object, the `id` property is obligatory. Additional properties
+ * can be used when customizing the mention feature bahavior
+ * (see {@glink features/mentions#customizing-the-autocomplete-list "Customizing the autocomplete list"}
+ * and {@glink features/mentions#customizing-the-output "Customizing the output"} sections).
+ *
+ * ```ts
+ * ClassicEditor
+ * 	.create( editorElement, {
+ * 		plugins: [ Mention, ... ],
+ * 		mention: {
+ * 			feeds: [
+ * 				// Feed items as objects.
+ * 				{
+ * 					marker: '@',
+ * 					feed: [
+ * 						{
+ * 							id: '@Barney',
+ * 							fullName: 'Barney Bloom'
+ * 						},
+ * 						{
+ * 							id: '@Lily',
+ * 							fullName: 'Lily Smith'
+ * 						},
+ * 						{
+ * 							id: '@Marshall',
+ * 							fullName: 'Marshall McDonald'
+ * 						},
+ * 						{
+ * 							id: '@Robin',
+ * 							fullName: 'Robin Hood'
+ * 						},
+ * 						{
+ * 							id: '@Ted',
+ * 							fullName: 'Ted Cruze'
+ * 						},
+ * 						// ...
+ * 					]
+ * 				},
+ *
+ * 				// Feed items as plain strings.
+ * 				{
+ * 					marker: '#',
+ * 					feed: [ 'wysiwyg', 'rte', 'rich-text-edior', 'collaboration', 'real-time', ... ]
+ * 				},
+ * 			]
+ * 		}
+ * 	} )
+ * 	.then( ... )
+ * 	.catch( ... );
+ * ```
+ */
+export type MentionFeedItem = string | MentionFeedObjectItem;
+export type MentionFeedObjectItem = {
+    /**
+     * A unique ID of the mention. It must start with the marker character.
+     */
+    id: string;
+    /**
+     * Text inserted into the editor when creating a mention.
+     */
+    text?: string;
+};

package/dist/types/mentionediting.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @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 mention/mentionediting
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import type { Element } from 'ckeditor5/src/engine.js';
+import type { MentionAttribute } from './mention.js';
+/**
+ * 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">`.
+ */
+export default class MentionEditing extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "MentionEditing";
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+}
+/**
+ * @internal
+ */
+export declare function _addMentionAttributes(baseMentionData: {
+    id: string;
+    _text: string;
+}, data?: Record<string, unknown>): MentionAttribute;
+/**
+ * Creates a mention attribute value from the provided view element and optional data.
+ *
+ * This function is exposed as
+ * {@link module:mention/mention~Mention#toMentionAttribute `editor.plugins.get( 'Mention' ).toMentionAttribute()`}.
+ *
+ * @internal
+ */
+export declare function _toMentionAttribute(viewElementOrMention: Element, data?: Record<string, unknown>): MentionAttribute | undefined;

package/dist/types/mentionui.d.ts

@@ -0,0 +1,102 @@
+/**
+ * @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 mention/mentionui
+ */
+import { Plugin, type Editor } from 'ckeditor5/src/core.js';
+import { ContextualBalloon } from 'ckeditor5/src/ui.js';
+/**
+ * The mention UI feature.
+ */
+export default class MentionUI extends Plugin {
+    /**
+     * The mention view.
+     */
+    private readonly _mentionsView;
+    /**
+     * Stores mention feeds configurations.
+     */
+    private _mentionsConfigurations;
+    /**
+     * The contextual balloon plugin instance.
+     */
+    private _balloon;
+    private _items;
+    private _lastRequested?;
+    /**
+     * Debounced feed requester. It uses `lodash#debounce` method to delay function call.
+     */
+    private _requestFeedDebounced;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "MentionUI";
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof ContextualBalloon];
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Returns true when {@link #_mentionsView} is in the {@link module:ui/panel/balloon/contextualballoon~ContextualBalloon} and it is
+     * currently visible.
+     */
+    private get _isUIVisible();
+    /**
+     * Creates the {@link #_mentionsView}.
+     */
+    private _createMentionView;
+    /**
+     * Returns item renderer for the marker.
+     */
+    private _getItemRenderer;
+    /**
+     * Requests a feed from a configured callbacks.
+     */
+    private _requestFeed;
+    /**
+     * Registers a text watcher for the marker.
+     */
+    private _setupTextWatcher;
+    /**
+     * Handles the feed response event data.
+     */
+    private _handleFeedResponse;
+    /**
+     * Shows the mentions balloon. If the panel is already visible, it will reposition it.
+     */
+    private _showOrUpdateUI;
+    /**
+     * Hides the mentions balloon and removes the 'mention' marker from the markers collection.
+     */
+    private _hideUIAndRemoveMarker;
+    /**
+     * Renders a single item in the autocomplete list.
+     */
+    private _renderItem;
+    /**
+     * Creates a position options object used to position the balloon panel.
+     *
+     * @param mentionMarker
+     * @param preferredPosition The name of the last matched position name.
+     */
+    private _getBalloonPanelPositionData;
+}
+/**
+ * Creates a RegExp pattern for the marker.
+ *
+ * Function has to be exported to achieve 100% code coverage.
+ */
+export declare function createRegExp(marker: string, minimumCharacters: number): RegExp;

package/dist/types/ui/domwrapperview.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @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 mention/ui/domwrapperview
+ */
+import { View } from 'ckeditor5/src/ui.js';
+import type { Locale } from 'ckeditor5/src/utils.js';
+/**
+ * This class wraps DOM element as a CKEditor5 UI View.
+ *
+ * It allows to render any DOM element and use it in mentions list.
+ */
+export default class DomWrapperView extends View {
+    /**
+     * The DOM element for which wrapper was created.
+     */
+    domElement: HTMLElement;
+    /**
+     * Controls whether the dom wrapper view is "on". This is in line with {@link module:ui/button/button~Button#isOn} property.
+     *
+     * @observable
+     * @default true
+     */
+    isOn: boolean;
+    /**
+     * Creates an instance of {@link module:mention/ui/domwrapperview~DomWrapperView} class.
+     *
+     * Also see {@link #render}.
+     */
+    constructor(locale: Locale, domElement: HTMLElement);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * Focuses the DOM element.
+     */
+    focus(): void;
+}

package/dist/types/ui/mentionlistitemview.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @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 mention/ui/mentionlistitemview
+ */
+import { ListItemView } from 'ckeditor5/src/ui.js';
+import type { MentionFeedItem } from '../mentionconfig.js';
+export default class MentionListItemView extends ListItemView {
+    item: MentionFeedItem;
+    marker: string;
+    highlight(): void;
+    removeHighlight(): void;
+}

package/dist/types/ui/mentionsview.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @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 mention/ui/mentionsview
+ */
+import { ListView } from 'ckeditor5/src/ui.js';
+import { type Locale } from 'ckeditor5/src/utils.js';
+import type MentionListItemView from './mentionlistitemview.js';
+import '../../theme/mentionui.css';
+/**
+ * The mention ui view.
+ */
+export default class MentionsView extends ListView {
+    selected: MentionListItemView | undefined;
+    position: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale: Locale);
+    /**
+     * {@link #select Selects} the first item.
+     */
+    selectFirst(): void;
+    /**
+     * Selects next item to the currently {@link #select selected}.
+     *
+     * If the last item is already selected, it will select the first item.
+     */
+    selectNext(): void;
+    /**
+     * Selects previous item to the currently {@link #select selected}.
+     *
+     * If the first item is already selected, it will select the last item.
+     */
+    selectPrevious(): void;
+    /**
+     * 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: number): void;
+    /**
+     * Triggers the `execute` event on the {@link #select selected} item.
+     */
+    executeSelected(): void;
+    /**
+     * 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)
+     */
+    private _isItemVisibleInScrolledArea;
+}