Core Plugin System

/**
 * The mention plugin that provides smart autocompletion for @mentions and #tags.
 * This is the main entry point for the mention feature.
 */
class Mention extends Plugin {
    static get pluginName(): 'Mention';
    static get isOfficialPlugin(): true;
    static get requires(): [typeof MentionEditing, typeof MentionUI];
    
    /**
     * Creates a mention attribute value from the provided view element and additional data.
     * @param viewElement - The view element containing mention data
     * @param data - Additional data to be stored in the mention attribute
     * @returns Mention attribute with merged data or undefined if conversion fails
     */
    toMentionAttribute<T extends Record<string, unknown>>(
        viewElement: ModelElement, 
        data?: T
    ): (MentionAttribute & T) | undefined;
    
    /**
     * Creates a mention attribute value from the provided view element.
     * @param viewElement - The view element containing mention data
     * @returns Mention attribute or undefined if conversion fails
     */
    toMentionAttribute(viewElement: ModelElement): MentionAttribute | undefined;
}

import { ClassicEditor } from "@ckeditor/ckeditor5-editor-classic";
import { Mention } from "@ckeditor/ckeditor5-mention";

// Basic plugin setup
ClassicEditor.create(editorElement, {
    plugins: [Mention],
    mention: {
        feeds: [
            {
                marker: '@',
                feed: ['@alice', '@bob', '@charlie']
            }
        ]
    }
});

// Access mention plugin and convert elements
const editor = await ClassicEditor.create(/* ... */);
const mentionPlugin = editor.plugins.get('Mention');

// Convert view element with additional data
const mentionAttr = mentionPlugin.toMentionAttribute(viewElement, {
    userId: '123',
    department: 'Engineering'
});

/**
 * The mention editing feature that handles model-view conversion and data validation.
 * Introduces the mention attribute in the model and handles upcast/downcast conversions.
 */
class MentionEditing extends Plugin {
    static get pluginName(): 'MentionEditing';
    static get isOfficialPlugin(): true;
    
    /**
     * Initializes the editing functionality including schema extension,
     * conversion setup, and command registration.
     */
    init(): void;
}

/**
 * The mention UI feature that manages the dropdown interface and user interactions.
 * Handles mention feed requests, dropdown positioning, and keyboard navigation.
 */
class MentionUI extends Plugin {
    static get pluginName(): 'MentionUI';
    static get isOfficialPlugin(): true;
    static get requires(): [typeof ContextualBalloon];
    
    /**
     * Initializes the UI functionality including event listeners,
     * feed configuration, and balloon setup.
     */
    init(): void;
    
    /**
     * Destroys the UI components to prevent memory leaks.
     */
    destroy(): void;
}

/**
 * The mention command that handles mention insertion into the editor.
 * Registered as 'mention' command in the editor's command collection.
 */
class MentionCommand extends Command {
    /**
     * Executes the mention insertion command.
     * @param options - Command execution options
     */
    execute(options: {
        mention: string | { id: string; [key: string]: unknown };
        marker: string;
        text?: string;
        range?: ModelRange;
    }): void;
    
    /**
     * Refreshes the command state based on current selection.
     */
    refresh(): void;
}

// Execute mention command programmatically
const editor = await ClassicEditor.create(/* ... */);

// Insert a simple mention
editor.execute('mention', {
    mention: '@alice',
    marker: '@',
    range: editor.model.document.selection.getFirstRange()
});

// Insert mention with custom data and text
editor.execute('mention', {
    mention: {
        id: '@alice',
        userId: '123',
        fullName: 'Alice Johnson'
    },
    marker: '@',
    text: 'Alice Johnson',
    range: targetRange
});

/**
 * Adds mention attributes with UID generation.
 * @internal
 */
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.
 * @internal
 */
function _toMentionAttribute(
    viewElementOrMention: ModelElement,
    data?: Record<string, unknown>
): MentionAttribute | undefined;

/**
 * Creates a RegExp pattern for the marker.
 * Exported as _createMentionMarkerRegExp for advanced usage.
 * @internal
 */
function _createMentionMarkerRegExp(marker: string, minimumCharacters: number): RegExp;