@ckeditor/ckeditor5-mention 39.0.1 → 40.0.0

package/src/mention.d.ts

@@ -1,66 +1,77 @@
-/**
- * @license Copyright (c) 2003-2023, 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';
-import type { Element } from 'ckeditor5/src/engine';
-import MentionEditing from './mentionediting';
-import MentionUI from './mentionui';
-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 optional 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 viewElement
-     * @param data Additional data to be stored in the mention attribute.
-     */
-    toMentionAttribute(viewElement: Element, data?: MentionAttribute): 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;
-};
+/**
+ * @license Copyright (c) 2003-2023, 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';
+import type { Element } from 'ckeditor5/src/engine';
+import MentionEditing from './mentionediting';
+import MentionUI from './mentionui';
+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/src/mention.js

@@ -1,47 +1,33 @@
-/**
- * @license Copyright (c) 2003-2023, 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';
-import MentionEditing, { _toMentionAttribute } from './mentionediting';
-import MentionUI from './mentionui';
-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 optional 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 viewElement
-     * @param data Additional data to be stored in the mention attribute.
-     */
-    toMentionAttribute(viewElement, data) {
-        return _toMentionAttribute(viewElement, data);
-    }
-    /**
-     * @inheritDoc
-     */
-    static get pluginName() {
-        return 'Mention';
-    }
-    /**
-     * @inheritDoc
-     */
-    static get requires() {
-        return [MentionEditing, MentionUI];
-    }
-}
+/**
+ * @license Copyright (c) 2003-2023, 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';
+import MentionEditing, { _toMentionAttribute } from './mentionediting';
+import MentionUI from './mentionui';
+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 {
+    toMentionAttribute(viewElement, data) {
+        return _toMentionAttribute(viewElement, data);
+    }
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'Mention';
+    }
+    /**
+     * @inheritDoc
+     */
+    static get requires() {
+        return [MentionEditing, MentionUI];
+    }
+}

package/src/mentioncommand.d.ts

@@ -1,75 +1,77 @@
-/**
- * @license Copyright (c) 2003-2023, 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';
-import type { Range } from 'ckeditor5/src/engine';
-import type { MentionAttribute } from './mention';
-/**
- * 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 | MentionAttribute;
-        marker: string;
-        text?: string;
-        range?: Range;
-    }): void;
-}
+/**
+ * @license Copyright (c) 2003-2023, 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';
+import type { Range } from 'ckeditor5/src/engine';
+/**
+ * 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;
+}