@znuny/ckeditor5-autocomplete-plugin/src/Interfaces/CompletionElement.d.ts

A plugin for CKEditor 5 that provides an extendable autocomplete functionality with predefined mention and HTML replacement logic.

/**
 * @copyright Copyright (c) 2024, Znuny GmbH.
 *
 * @license GNU GPL version 3
 *
 * This software comes with ABSOLUTELY NO WARRANTY. For details, see
 * the enclosed file COPYING for license information (GPL). If you
 * did not receive this file, see https://www.gnu.org/licenses/gpl-3.0.txt.
 */
/**
 * Function that takes a completion element and renders it as HTMLElement or string.
 */
export type CompletionElementRenderer = (completionElement: CompletionElement) => HTMLElement | string;
/**
 * Definition of a {name}="{value}" attribute.
 */
export interface CompletionElementAttribute {
    name: string;
    value: string;
}
/**
 * Available configuration options for a completion element.
 *
 * A completion element can be used in two different modes.
 *
 * Mention:
 * - enabled when useAsHTMLReplacement = false or is just not defined (default)
 * - replaces the marker + typed completion matching characters with the content value in plain text mode
 * - this will create a span HTML element in source code, containing 'data-mention' as well as all custom data attributes (configured within the dataAttributes array)
 *
 * HTML replacement:
 * - enabled when useAsHTMLReplacement = true
 * - replaces the marker + typed completion matching characters with the content value in HTML mode
 */
export interface CompletionElement {
    /**
     * Custom string (without matching marker prefix) that can be used for element matching (recommended).
     * It is also the default identifying element that is used within the data-mention="..." HTML attribute,
     * if the completion element is used as mention. (useAsHTMLReplacement = false)
     */
    name?: string;
    /**
     * String or HTMLElement (useAsHTMLReplacement required then) that will be set as completion replacement.
     * It can also be used for element matching (without matching marker) (not recommended).
     *
     * Since CKEditor will cast the inserted HTML into its internal model system this may not work well with fully custom HTML.
     * Instead it's recommended to use HTML (string) generated by the CKEditor 5 itself.
     */
    content: string | HTMLElement;
    /**
     * Enabled HTML replacement mode to insert content as HTML at the position of the currently typing completion. Defaults to false.
     */
    useAsHTMLReplacement?: boolean;
    /**
     * Insert custom attributes to the mention HTML element. (only in mention mode)
     * The 'class' and 'data-mention' attributes can not be overwritten!
     */
    attributes?: Array<CompletionElementAttribute>;
    /**
     * A function that renders a completion element to the selection ui (dropdown).
     * This will overwrite the default renderer as well as the completion group configured completionElementRenderer.
     */
    completionElementRenderer?: CompletionElementRenderer;
}