@znuny/ckeditor5-autocomplete-plugin/src/Interfaces/CompletionGroupConfiguration.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.
 */
import type { CompletionElement, CompletionElementRenderer } from './CompletionElement';
import type { Model, Batch, ModelRange, DataController } from 'ckeditor5/src/engine.js';
export declare enum InputMatchingStrategy {
    NAME_STARTS_WITH = "nameStartsWith",
    NAME_INCLUDES = "nameIncludes",
    CONTENT_STARTS_WITH = "contentStartsWith",
    CONTENT_INCLUDES = "contentIncludes",
    EVERYTHING = "everything"
}
/**
 * Function that should return an already filtered array of completion elements based on the search string (that does not contain the marker prefix).
 */
export type CompletionElementsCallback = (searchString: string) => Promise<Array<CompletionElement>> | Array<CompletionElement>;
/**
 * @param data contains the arguments, that are coming out of the TextWatcherMatchedEvent typed TextWatcher
 */
export type ConfirmedSelectionHandlerCallback = (editorModel: Model, editorData: DataController, data: {
    text: string;
    range: ModelRange;
    batch?: Batch;
} & Record<string, unknown>, selectedCompletionElement: CompletionElement) => Promise<void> | void;
/**
 * Function to check marker matching logic. Usually something like inputText.includes("##").
 */
export type MarkerMatchingCallback = (inputText: string, marker: string) => boolean;
/**
 * Available configuration options for a group of completion elements, that share the same behaviour, like the same matchingMarker.
 */
export interface CompletionGroupConfiguration {
    /**
     * The prefix characters, which triggers autocompletion for the completion group. It has to be at least a single character.
     */
    matchingMarker: string;
    /**
     * Overwrites the default marker matching logic.
     * It decides whether a completion group is responsible for further completion handling for a possibly found marker or not.
     *
     * Default marker matching is a "includes" string check of the currently typing word.
     * If a marker would be "##", the default markerMatchingCallback check is implemented like getLastWordFromText(inputTest).includes("##").
     * Markers are always checked case sensitive!
     */
    markerMatchingCallback?: MarkerMatchingCallback;
    /**
     * Option to test all possible markers of a selection (from first to last) until getting at least one matching completion element.
     * Since this functionality could lead to higher computing load, as well as an unexpected selection ui position and completions result set
     * when also using the "combineResultOfCompletionGroupsWithSameMarker" option, it's disabled by default.
     *
     * By default, only the marker closest to the cursor is checked.
     *
     * Defaults to false.
     */
    testAllPossibleMarkersOfASelection?: boolean;
    /**
     * Array of objects that describes the specific completion elements of this completion group.
     *
     * Providing the callback function (based on a searchString that does not contain the marker prefix), makes the matchingHandler option obviously obsolete.
     * Set completionMatchingHandler = 'everything' to archive that.
     */
    completions: Array<CompletionElement> | CompletionElementsCallback;
    /**
     * InputMatchingStrategy (like 'nameStartsWith') to test which completion elements should be offered by the selection ui.
     * Only works if completions is an array of completion elements (CompletionElementInterface[]).
     * When using a custom callback for completions, this should be set to 'everything'.
     *
     * If you would like to use a custom completion matching handler on your completions array (instead of a predefined one),
     * you can archive this by using a completions callback that filters the completion elements before giving them into the autocomplete plugin.
     */
    completionMatchingHandler: InputMatchingStrategy;
    /**
     * Defines whether a chosen InputMatchingStrategy (for completions only, not markers!) should be applied case sensitive or not. Defaults to false.
     */
    completionMatchingHandlerCaseSensitivity?: boolean;
    /**
     * Determines whether the selection interface displays selection options even if only the marker matches and no other characters have been entered. Defaults to false.
     */
    offerCompletionOptionsWithMarkerMatchingOnly?: boolean;
    /**
     * Specify how many available completion elements of this group will be shown in the selection dropdown list. Defaults to 10.
     *
     * To show all available (matching) elements in the selection ui, set this to -1.
     */
    selectionDropdownLimit?: number;
    /**
     * A function that will be called instead of the default behaviour (mention insertion / replacement) when selecting a completion element from the selection ui (dropdown).
     */
    confirmedSelectionHandler?: ConfirmedSelectionHandlerCallback;
    /**
     * A function that renders a completion element to the selection ui (dropdown).
     *
     * This will overwrite the default renderer for this group, but will be overwritten by a completionElementRenderer callback, that is configured for a specific completion element.
     */
    completionElementRenderer?: CompletionElementRenderer;
}