| 1 | /**
|
| 2 | * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
|
| 3 | * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
|
| 4 | */
|
| 5 | /**
|
| 6 | * The inline autoformatting engine. It allows to format various inline patterns. For example,
|
| 7 | * it can be configured to make "foo" bold when typed `**foo**` (the `**` markers will be removed).
|
| 8 | *
|
| 9 | * The autoformatting operation is integrated with the undo manager,
|
| 10 | * so the autoformatting step can be undone if the user's intention was not to format the text.
|
| 11 | *
|
| 12 | * See the {@link module:autoformat/inlineautoformatediting~inlineAutoformatEditing `inlineAutoformatEditing`} documentation
|
| 13 | * to learn how to create custom inline autoformatters. You can also use
|
| 14 | * the {@link module:autoformat/autoformat~Autoformat} feature which enables a set of default autoformatters
|
| 15 | * (lists, headings, bold and italic).
|
| 16 | *
|
| 17 | * @module autoformat/inlineautoformatediting
|
| 18 | */
|
| 19 | import type { Editor } from 'ckeditor5/src/core.js';
|
| 20 | import type { Range, Writer } from 'ckeditor5/src/engine.js';
|
| 21 | import type Autoformat from './autoformat.js';
|
| 22 | export type TestCallback = (text: string) => {
|
| 23 | remove: Array<Array<number>>;
|
| 24 | format: Array<Array<number>>;
|
| 25 | };
|
| 26 | /**
|
| 27 | * Enables autoformatting mechanism for a given {@link module:core/editor/editor~Editor}.
|
| 28 | *
|
| 29 | * It formats the matched text by applying the given model attribute or by running the provided formatting callback.
|
| 30 | * On every {@link module:engine/model/document~Document#event:change:data data change} in the model document
|
| 31 | * the autoformatting engine checks the text on the left of the selection
|
| 32 | * and executes the provided action if the text matches given criteria (regular expression or callback).
|
| 33 | *
|
| 34 | * @param editor The editor instance.
|
| 35 | * @param plugin The autoformat plugin instance.
|
| 36 | * @param testRegexpOrCallback The regular expression or callback to execute on text.
|
| 37 | * Provided regular expression *must* have three capture groups. The first and the third capture group
|
| 38 | * should match opening and closing delimiters. The second capture group should match the text to format.
|
| 39 | *
|
| 40 | * ```ts
|
| 41 | * // Matches the `**bold text**` pattern.
|
| 42 | * // There are three capturing groups:
|
| 43 | * // - The first to match the starting `**` delimiter.
|
| 44 | * // - The second to match the text to format.
|
| 45 | * // - The third to match the ending `**` delimiter.
|
| 46 | * inlineAutoformatEditing( editor, plugin, /(\*\*)([^\*]+?)(\*\*)$/g, formatCallback );
|
| 47 | * ```
|
| 48 | *
|
| 49 | * When a function is provided instead of the regular expression, it will be executed with the text to match as a parameter.
|
| 50 | * The function should return proper "ranges" to delete and format.
|
| 51 | *
|
| 52 | * ```ts
|
| 53 | * {
|
| 54 | * remove: [
|
| 55 | * [ 0, 1 ], // Remove the first letter from the given text.
|
| 56 | * [ 5, 6 ] // Remove the 6th letter from the given text.
|
| 57 | * ],
|
| 58 | * format: [
|
| 59 | * [ 1, 5 ] // Format all letters from 2nd to 5th.
|
| 60 | * ]
|
| 61 | * }
|
| 62 | * ```
|
| 63 | *
|
| 64 | * @param formatCallback A callback to apply actual formatting.
|
| 65 | * It should return `false` if changes should not be applied (e.g. if a command is disabled).
|
| 66 | *
|
| 67 | * ```ts
|
| 68 | * inlineAutoformatEditing( editor, plugin, /(\*\*)([^\*]+?)(\*\*)$/g, ( writer, rangesToFormat ) => {
|
| 69 | * const command = editor.commands.get( 'bold' );
|
| 70 | *
|
| 71 | * if ( !command.isEnabled ) {
|
| 72 | * return false;
|
| 73 | * }
|
| 74 | *
|
| 75 | * const validRanges = editor.model.schema.getValidRanges( rangesToFormat, 'bold' );
|
| 76 | *
|
| 77 | * for ( let range of validRanges ) {
|
| 78 | * writer.setAttribute( 'bold', true, range );
|
| 79 | * }
|
| 80 | * } );
|
| 81 | * ```
|
| 82 | */
|
| 83 | export default function inlineAutoformatEditing(editor: Editor, plugin: Autoformat, testRegexpOrCallback: RegExp | TestCallback, formatCallback: (writer: Writer, rangesToFormat: Array<Range>) => boolean | undefined): void;
|