@ckeditor/ckeditor5-typing 35.2.1 → 35.3.0

package/src/deleteobserver.js

@@ -2,128 +2,221 @@
  * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
-
 /**
  * @module typing/deleteobserver
  */
-
 import Observer from '@ckeditor/ckeditor5-engine/src/view/observer/observer';
 import DomEventData from '@ckeditor/ckeditor5-engine/src/view/observer/domeventdata';
 import BubblingEventInfo from '@ckeditor/ckeditor5-engine/src/view/observer/bubblingeventinfo';
-import { keyCodes } from '@ckeditor/ckeditor5-utils/src/keyboard';
-import env from '@ckeditor/ckeditor5-utils/src/env';
-import { isShiftDeleteOnNonCollapsedSelection } from './utils/utils';
-
+import { env, keyCodes } from '@ckeditor/ckeditor5-utils';
+const DELETE_CHARACTER = 'character';
+const DELETE_WORD = 'word';
+const DELETE_CODE_POINT = 'codePoint';
+const DELETE_SELECTION = 'selection';
+const DELETE_BACKWARD = 'backward';
+const DELETE_FORWARD = 'forward';
+const DELETE_EVENT_TYPES = {
+    // --------------------------------------- Backward delete types -----------------------------------------------------
+    // This happens in Safari on Mac when some content is selected and Ctrl + K is pressed.
+    deleteContent: {
+        unit: DELETE_SELECTION,
+        // According to the Input Events Level 2 spec, this delete type has no direction
+        // but to keep things simple, let's default to backward.
+        direction: DELETE_BACKWARD
+    },
+    // Chrome and Safari on Mac: Backspace or Ctrl + H
+    deleteContentBackward: {
+        // This kind of deletions must be done on the code point-level instead of target range provided by the DOM beforeinput event.
+        // Take for instance "👨‍👩‍👧‍👧", it equals:
+        //
+        //	* [ "👨", "ZERO WIDTH JOINER", "👩", "ZERO WIDTH JOINER", "👧", "ZERO WIDTH JOINER", "👧" ]
+        //	* or simply "\u{1F468}\u200D\u{1F469}\u200D\u{1F467}\u200D\u{1F467}"
+        //
+        // The range provided by the browser would cause the entire multi-byte grapheme to disappear while the user
+        // intention when deleting backwards ("👨‍👩‍👧‍👧[]", then backspace) is gradual "decomposition" (first to "👨‍👩‍👧‍[]",
+        // then to "👨‍👩‍[]", etc.).
+        //
+        //	* "👨‍👩‍👧‍👧[]" + backward delete (by code point)  -> results in "👨‍👩‍👧[]", removed the last "👧" 👍
+        //	* "👨‍👩‍👧‍👧[]" + backward delete (by character)  -> results in "[]", removed the whole grapheme 👎
+        //
+        // Deleting by code-point is simply a better UX. See "deleteContentForward" to learn more.
+        unit: DELETE_CODE_POINT,
+        direction: DELETE_BACKWARD
+    },
+    // On Mac: Option + Backspace.
+    // On iOS: Hold the backspace for a while and the whole words will start to disappear.
+    deleteWordBackward: {
+        unit: DELETE_WORD,
+        direction: DELETE_BACKWARD
+    },
+    // Safari on Mac: Cmd + Backspace
+    deleteHardLineBackward: {
+        unit: DELETE_SELECTION,
+        direction: DELETE_BACKWARD
+    },
+    // Chrome on Mac: Cmd + Backspace.
+    deleteSoftLineBackward: {
+        unit: DELETE_SELECTION,
+        direction: DELETE_BACKWARD
+    },
+    // --------------------------------------- Forward delete types -----------------------------------------------------
+    // Chrome on Mac: Fn + Backspace or Ctrl + D
+    // Safari on Mac: Ctrl + K or Ctrl + D
+    deleteContentForward: {
+        // Unlike backward delete, this delete must be performed by character instead of by code point, which
+        // provides the best UX for working with accented letters.
+        // Take, for example "b̂" ("\u0062\u0302", or [ "LATIN SMALL LETTER B", "COMBINING CIRCUMFLEX ACCENT" ]):
+        //
+        //	* "b̂[]" + backward delete (by code point)  -> results in "b[]", removed the combining mark 👍
+        //	* "[]b̂" + forward delete (by code point)   -> results in "[]^", a bare combining mark does that not make sense when alone 👎
+        //	* "[]b̂" + forward delete (by character)    -> results in "[]", removed both "b" and the combining mark 👍
+        //
+        // See: "deleteContentBackward" to learn more.
+        unit: DELETE_CHARACTER,
+        direction: DELETE_FORWARD
+    },
+    // On Mac: Fn + Option + Backspace.
+    deleteWordForward: {
+        unit: DELETE_WORD,
+        direction: DELETE_FORWARD
+    },
+    // Chrome on Mac: Ctrl + K (you have to disable the Link plugin first, though, because it uses the same keystroke)
+    // This is weird that it does not work in Safari on Mac despite being listed in the official shortcuts listing
+    // on Apple's webpage.
+    deleteHardLineForward: {
+        unit: DELETE_SELECTION,
+        direction: DELETE_FORWARD
+    },
+    // At this moment there is no known way to trigger this event type but let's keep it for the symmetry with
+    // deleteSoftLineBackward.
+    deleteSoftLineForward: {
+        unit: DELETE_SELECTION,
+        direction: DELETE_FORWARD
+    }
+};
 /**
  * Delete observer introduces the {@link module:engine/view/document~Document#event:delete} event.
  *
  * @extends module:engine/view/observer/observer~Observer
  */
 export default class DeleteObserver extends Observer {
-	/**
-	 * @inheritDoc
-	 */
-	constructor( view ) {
-		super( view );
-
-		const document = view.document;
-		let sequence = 0;
-
-		document.on( 'keyup', ( evt, data ) => {
-			if ( data.keyCode == keyCodes.delete || data.keyCode == keyCodes.backspace ) {
-				sequence = 0;
-			}
-		} );
-
-		document.on( 'keydown', ( evt, data ) => {
-			// Do not fire the `delete` event, if Shift + Delete key combination was pressed on a non-collapsed selection on Windows.
-			//
-			// The Shift + Delete key combination should work in the same way as the `cut` event on a non-collapsed selection on Windows.
-			// In fact, the native `cut` event is actually emitted in this case, but with lower priority. Therefore, in order to handle the
-			// Shift + Delete key combination correctly, it is enough not to emit the `delete` event.
-			if ( env.isWindows && isShiftDeleteOnNonCollapsedSelection( data, document ) ) {
-				return;
-			}
-
-			const deleteData = {};
-
-			if ( data.keyCode == keyCodes.delete ) {
-				deleteData.direction = 'forward';
-				deleteData.unit = 'character';
-			} else if ( data.keyCode == keyCodes.backspace ) {
-				deleteData.direction = 'backward';
-				deleteData.unit = 'codePoint';
-			} else {
-				return;
-			}
-
-			const hasWordModifier = env.isMac ? data.altKey : data.ctrlKey;
-			deleteData.unit = hasWordModifier ? 'word' : deleteData.unit;
-			deleteData.sequence = ++sequence;
-
-			fireViewDeleteEvent( evt, data.domEvent, deleteData );
-		} );
-
-		// `beforeinput` is handled only for Android devices. Desktop Chrome and iOS are skipped because they are working fine now.
-		if ( env.isAndroid ) {
-			document.on( 'beforeinput', ( evt, data ) => {
-				// If event type is other than `deleteContentBackward` then this is not deleting.
-				if ( data.domEvent.inputType != 'deleteContentBackward' ) {
-					return;
-				}
-
-				const deleteData = {
-					unit: 'codepoint',
-					direction: 'backward',
-					sequence: 1
-				};
-
-				// Android IMEs may change the DOM selection on `beforeinput` event so that the selection contains all the text
-				// that the IME wants to remove. We will pass this information to `delete` event so proper part of the content is removed.
-				//
-				// Sometimes it is only expanding by a one character (in case of collapsed selection). In this case we don't need to
-				// set a different selection to remove, it will work just fine.
-				const domSelection = data.domTarget.ownerDocument.defaultView.getSelection();
-
-				if ( domSelection.anchorNode == domSelection.focusNode && domSelection.anchorOffset + 1 != domSelection.focusOffset ) {
-					deleteData.selectionToRemove = view.domConverter.domSelectionToView( domSelection );
-				}
-
-				fireViewDeleteEvent( evt, data.domEvent, deleteData );
-			} );
-		}
-
-		function fireViewDeleteEvent( originalEvent, domEvent, deleteData ) {
-			const event = new BubblingEventInfo( document, 'delete', document.selection.getFirstRange() );
-
-			document.fire( event, new DomEventData( document, domEvent, deleteData ) );
-
-			// Stop the original event if `delete` event was stopped.
-			// https://github.com/ckeditor/ckeditor5/issues/753
-			if ( event.stop.called ) {
-				originalEvent.stop();
-			}
-		}
-	}
-
-	/**
-	 * @inheritDoc
-	 */
-	observe() {}
+    /**
+     * @inheritDoc
+     */
+    constructor(view) {
+        super(view);
+        const document = view.document;
+        // It matters how many subsequent deletions were made, e.g. when the backspace key was pressed and held
+        // by the user for some time. For instance, if such scenario ocurred and the heading the selection was
+        // anchored to was the only content of the editor, it will not be converted into a paragraph (the user
+        // wanted to clean it up, not remove it, it's about UX). Check out the DeleteCommand implementation to learn more.
+        //
+        // Fun fact: Safari on Mac won't fire beforeinput for backspace in an empty heading (only content).
+        let sequence = 0;
+        document.on('keydown', () => {
+            sequence++;
+        });
+        document.on('keyup', () => {
+            sequence = 0;
+        });
+        document.on('beforeinput', (evt, data) => {
+            if (!this.isEnabled) {
+                return;
+            }
+            const { targetRanges, domEvent, inputType } = data;
+            const deleteEventSpec = DELETE_EVENT_TYPES[inputType];
+            if (!deleteEventSpec) {
+                return;
+            }
+            const deleteData = {
+                direction: deleteEventSpec.direction,
+                unit: deleteEventSpec.unit,
+                sequence
+            };
+            if (deleteData.unit == DELETE_SELECTION) {
+                deleteData.selectionToRemove = view.createSelection(targetRanges[0]);
+            }
+            // The default deletion unit for deleteContentBackward is a single code point
+            // but on Android it sometimes passes a wider target range, so we need to change
+            // the unit of deletion to include the whole range to be removed and not a single code point.
+            if (env.isAndroid && inputType === 'deleteContentBackward') {
+                // On Android, deleteContentBackward has sequence 1 by default.
+                deleteData.sequence = 1;
+                // IME wants more than a single character to be removed.
+                if (targetRanges.length == 1 && (targetRanges[0].start.parent != targetRanges[0].end.parent ||
+                    targetRanges[0].start.offset + 1 != targetRanges[0].end.offset)) {
+                    deleteData.unit = DELETE_SELECTION;
+                    deleteData.selectionToRemove = view.createSelection(targetRanges);
+                }
+            }
+            const eventInfo = new BubblingEventInfo(document, 'delete', targetRanges[0]);
+            document.fire(eventInfo, new DomEventData(view, domEvent, deleteData));
+            // Stop the beforeinput event if `delete` event was stopped.
+            // https://github.com/ckeditor/ckeditor5/issues/753
+            if (eventInfo.stop.called) {
+                evt.stop();
+            }
+        });
+        // TODO: to be removed when https://bugs.chromium.org/p/chromium/issues/detail?id=1365311 is solved.
+        if (env.isBlink) {
+            enableChromeWorkaround(this);
+        }
+    }
+    /**
+     * @inheritDoc
+     */
+    observe() { }
+}
+// Enables workaround for the issue https://github.com/ckeditor/ckeditor5/issues/11904.
+function enableChromeWorkaround(observer) {
+    const view = observer.view;
+    const document = view.document;
+    let pressedKeyCode = null;
+    let beforeInputReceived = false;
+    document.on('keydown', (evt, { keyCode }) => {
+        pressedKeyCode = keyCode;
+        beforeInputReceived = false;
+    });
+    document.on('keyup', (evt, { keyCode, domEvent }) => {
+        const selection = document.selection;
+        const shouldFireDeleteEvent = observer.isEnabled &&
+            keyCode == pressedKeyCode &&
+            isDeleteKeyCode(keyCode) &&
+            !selection.isCollapsed &&
+            !beforeInputReceived;
+        pressedKeyCode = null;
+        if (shouldFireDeleteEvent) {
+            const targetRange = selection.getFirstRange();
+            const eventInfo = new BubblingEventInfo(document, 'delete', targetRange);
+            const deleteData = {
+                unit: DELETE_SELECTION,
+                direction: getDeleteDirection(keyCode),
+                selectionToRemove: selection
+            };
+            document.fire(eventInfo, new DomEventData(view, domEvent, deleteData));
+        }
+    });
+    document.on('beforeinput', (evt, { inputType }) => {
+        const deleteEventSpec = DELETE_EVENT_TYPES[inputType];
+        const isMatchingBeforeInput = isDeleteKeyCode(pressedKeyCode) &&
+            deleteEventSpec &&
+            deleteEventSpec.direction == getDeleteDirection(pressedKeyCode);
+        if (isMatchingBeforeInput) {
+            beforeInputReceived = true;
+        }
+    });
+    document.on('beforeinput', (evt, { inputType, data }) => {
+        const shouldIgnoreBeforeInput = pressedKeyCode == keyCodes.delete &&
+            inputType == 'insertText' &&
+            data == '\x7f'; // Delete character :P
+        if (shouldIgnoreBeforeInput) {
+            evt.stop();
+        }
+    }, { priority: 'high' });
+    function isDeleteKeyCode(keyCode) {
+        return keyCode == keyCodes.backspace || keyCode == keyCodes.delete;
+    }
+    function getDeleteDirection(keyCode) {
+        return keyCode == keyCodes.backspace ? DELETE_BACKWARD : DELETE_FORWARD;
+    }
 }
-
-/**
- * Event fired when the user tries to delete content (e.g. presses <kbd>Delete</kbd> or <kbd>Backspace</kbd>).
- *
- * Note: This event is fired by the {@link module:typing/deleteobserver~DeleteObserver observer}
- * (usually registered by the {@link module:typing/delete~Delete delete feature}).
- *
- * @event module:engine/view/document~Document#event:delete
- * @param {module:engine/view/observer/domeventdata~DomEventData} data
- * @param {'forward'|'delete'} data.direction The direction in which the deletion should happen.
- * @param {'character'|'codePoint'|'word'} data.unit The "amount" of content that should be deleted.
- * @param {Number} data.sequence A number describing which subsequent delete event it is without the key being released.
- * If it's 2 or more it means that the key was pressed and hold.
- * @param {module:engine/view/selection~Selection} [data.selectionToRemove] View selection which content should be removed. If not set,
- * current selection should be used.
- */

package/src/index.js

@@ -2,21 +2,15 @@
  * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
-
 /**
  * @module typing
  */
-
 export { default as Typing } from './typing';
 export { default as Input } from './input';
 export { default as Delete } from './delete';
-
 export { default as TextWatcher } from './textwatcher';
 export { default as TwoStepCaretMovement } from './twostepcaretmovement';
 export { default as TextTransformation } from './texttransformation';
-
 export { default as inlineHighlight } from './utils/inlinehighlight';
 export { default as findAttributeRange } from './utils/findattributerange';
 export { default as getLastTextLine } from './utils/getlasttextline';
-
-export * from './utils/injectunsafekeystrokeshandling';

package/src/input.js

@@ -2,42 +2,139 @@
  * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
-
 /**
  * @module typing/input
  */
-
 import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
-import InputCommand from './inputcommand';
-
-import injectUnsafeKeystrokesHandling from './utils/injectunsafekeystrokeshandling';
-import injectTypingMutationsHandling from './utils/injecttypingmutationshandling';
-
+import InsertTextCommand from './inserttextcommand';
+import InsertTextObserver from './inserttextobserver';
+import env from '@ckeditor/ckeditor5-utils/src/env';
+// Import config.typing declaration.
+import './typingconfig';
 /**
  * Handles text input coming from the keyboard or other input methods.
  *
  * @extends module:core/plugin~Plugin
  */
 export default class Input extends Plugin {
-	/**
-	 * @inheritDoc
-	 */
-	static get pluginName() {
-		return 'Input';
-	}
-
-	/**
-	 * @inheritDoc
-	 */
-	init() {
-		const editor = this.editor;
-
-		// TODO The above default configuration value should be defined using editor.config.define() once it's fixed.
-		const inputCommand = new InputCommand( editor, editor.config.get( 'typing.undoStep' ) || 20 );
-
-		editor.commands.add( 'input', inputCommand );
-
-		injectUnsafeKeystrokesHandling( editor );
-		injectTypingMutationsHandling( editor );
-	}
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'Input';
+    }
+    /**
+     * @inheritDoc
+     */
+    init() {
+        const editor = this.editor;
+        const model = editor.model;
+        const view = editor.editing.view;
+        const modelSelection = model.document.selection;
+        view.addObserver(InsertTextObserver);
+        // TODO The above default configuration value should be defined using editor.config.define() once it's fixed.
+        const insertTextCommand = new InsertTextCommand(editor, editor.config.get('typing.undoStep') || 20);
+        // Register `insertText` command and add `input` command as an alias for backward compatibility.
+        editor.commands.add('insertText', insertTextCommand);
+        editor.commands.add('input', insertTextCommand);
+        this.listenTo(view.document, 'insertText', (evt, data) => {
+            // Rendering is disabled while composing so prevent events that will be rendered by the engine
+            // and should not be applied by the browser.
+            if (!view.document.isComposing) {
+                data.preventDefault();
+            }
+            const { text, selection: viewSelection, resultRange: viewResultRange } = data;
+            // If view selection was specified, translate it to model selection.
+            const modelRanges = Array.from(viewSelection.getRanges()).map(viewRange => {
+                return editor.editing.mapper.toModelRange(viewRange);
+            });
+            let insertText = text;
+            // Typing in English on Android is firing composition events for the whole typed word.
+            // We need to check the target range text to only apply the difference.
+            if (env.isAndroid) {
+                const selectedText = Array.from(modelRanges[0].getItems()).reduce((rangeText, node) => {
+                    return rangeText + (node.is('$textProxy') ? node.data : '');
+                }, '');
+                if (selectedText) {
+                    if (selectedText.length <= insertText.length) {
+                        if (insertText.startsWith(selectedText)) {
+                            insertText = insertText.substring(selectedText.length);
+                            modelRanges[0].start = modelRanges[0].start.getShiftedBy(selectedText.length);
+                        }
+                    }
+                    else {
+                        if (selectedText.startsWith(insertText)) {
+                            // TODO this should be mapped as delete?
+                            modelRanges[0].start = modelRanges[0].start.getShiftedBy(insertText.length);
+                            insertText = '';
+                        }
+                    }
+                }
+            }
+            const insertTextCommandData = {
+                text: insertText,
+                selection: model.createSelection(modelRanges)
+            };
+            // @if CK_DEBUG_TYPING // if ( window.logCKETyping ) {
+            // @if CK_DEBUG_TYPING // 	console.log( '%c[Input]%c Execute insertText:',
+            // @if CK_DEBUG_TYPING // 		'font-weight: bold; color: green;', '',
+            // @if CK_DEBUG_TYPING // 		insertText,
+            // @if CK_DEBUG_TYPING // 		`[${ modelRanges[ 0 ].start.path }]-[${ modelRanges[ 0 ].end.path }]`
+            // @if CK_DEBUG_TYPING // 	);
+            // @if CK_DEBUG_TYPING // }
+            if (viewResultRange) {
+                insertTextCommandData.resultRange = editor.editing.mapper.toModelRange(viewResultRange);
+            }
+            editor.execute('insertText', insertTextCommandData);
+        });
+        if (env.isAndroid) {
+            // On Android with English keyboard, the composition starts just by putting caret
+            // at the word end or by selecting a table column. This is not a real composition started.
+            // Trigger delete content on first composition key pressed.
+            this.listenTo(view.document, 'keydown', (evt, data) => {
+                if (modelSelection.isCollapsed || data.keyCode != 229 || !view.document.isComposing) {
+                    return;
+                }
+                // @if CK_DEBUG_TYPING // if ( window.logCKETyping ) {
+                // @if CK_DEBUG_TYPING // 	console.log( '%c[Input]%c KeyDown 229 -> model.deleteContent()',
+                // @if CK_DEBUG_TYPING // 		'font-weight: bold; color: green;', '',
+                // @if CK_DEBUG_TYPING // 		`[${ modelSelection.getFirstPosition().path }]-[${ modelSelection.getLastPosition().path }]`
+                // @if CK_DEBUG_TYPING // 	);
+                // @if CK_DEBUG_TYPING // }
+                deleteSelectionContent(model, insertTextCommand);
+            });
+        }
+        else {
+            // Note: The priority must precede the CompositionObserver handler to call it before
+            // the renderer is blocked, because we want to render this change.
+            this.listenTo(view.document, 'compositionstart', () => {
+                if (modelSelection.isCollapsed) {
+                    return;
+                }
+                // @if CK_DEBUG_TYPING // if ( window.logCKETyping ) {
+                // @if CK_DEBUG_TYPING // 	console.log( '%c[Input]%c Composition start -> model.deleteContent()',
+                // @if CK_DEBUG_TYPING // 		'font-weight: bold; color: green;', '',
+                // @if CK_DEBUG_TYPING // 		`[${ modelSelection.getFirstPosition().path }]-[${ modelSelection.getLastPosition().path }]`
+                // @if CK_DEBUG_TYPING // 	);
+                // @if CK_DEBUG_TYPING // }
+                deleteSelectionContent(model, insertTextCommand);
+            });
+        }
+    }
+}
+function deleteSelectionContent(model, insertTextCommand) {
+    // By relying on the state of the input command we allow disabling the entire input easily
+    // by just disabling the input command. We could’ve used here the delete command but that
+    // would mean requiring the delete feature which would block loading one without the other.
+    // We could also check the editor.isReadOnly property, but that wouldn't allow to block
+    // the input without blocking other features.
+    if (!insertTextCommand.isEnabled) {
+        return;
+    }
+    const buffer = insertTextCommand.buffer;
+    buffer.lock();
+    model.enqueueChange(buffer.batch, () => {
+        model.deleteContent(model.document.selection);
+    });
+    buffer.unlock();
 }

package/src/inserttextcommand.js

@@ -0,0 +1,96 @@
+/**
+ * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module typing/inserttextcommand
+ */
+import Command from '@ckeditor/ckeditor5-core/src/command';
+import ChangeBuffer from './utils/changebuffer';
+/**
+ * The insert text command. Used by the {@link module:typing/input~Input input feature} to handle typing.
+ *
+ * @extends module:core/command~Command
+ */
+export default class InsertTextCommand extends Command {
+    /**
+     * Creates an instance of the command.
+     *
+     * @param {module:core/editor/editor~Editor} editor
+     * @param {Number} undoStepSize The maximum number of atomic changes
+     * which can be contained in one batch in the command buffer.
+     */
+    constructor(editor, undoStepSize) {
+        super(editor);
+        /**
+         * Typing's change buffer used to group subsequent changes into batches.
+         *
+         * @readonly
+         * @private
+         * @member {module:typing/utils/changebuffer~ChangeBuffer} #_buffer
+         */
+        this._buffer = new ChangeBuffer(editor.model, undoStepSize);
+    }
+    /**
+     * The current change buffer.
+     *
+     * @type {module:typing/utils/changebuffer~ChangeBuffer}
+     */
+    get buffer() {
+        return this._buffer;
+    }
+    /**
+     * @inheritDoc
+     */
+    destroy() {
+        super.destroy();
+        this._buffer.destroy();
+    }
+    /**
+     * Executes the input command. It replaces the content within the given range with the given text.
+     * Replacing is a two step process, first the content within the range is removed and then the new text is inserted
+     * at the beginning of the range (which after the removal is a collapsed range).
+     *
+     * @fires execute
+     * @param {Object} [options] The command options.
+     * @param {String} [options.text=''] The text to be inserted.
+     * @param {module:engine/model/selection~Selection} [options.selection] The selection in which the text is inserted.
+     * Inserting a text into a selection deletes the current content within selection ranges. If the selection is not specified,
+     * the current selection in the model will be used instead.
+     * // TODO note that those 2 options are exclusive (either selection or range)
+     * @param {module:engine/model/range~Range} [options.range] The range in which the text is inserted. Defaults
+     * to the first range in the current selection.
+     * @param {module:engine/model/range~Range} [options.resultRange] The range where the selection
+     * should be placed after the insertion. If not specified, the selection will be placed right after
+     * the inserted text.
+     */
+    execute(options = {}) {
+        const model = this.editor.model;
+        const doc = model.document;
+        const text = options.text || '';
+        const textInsertions = text.length;
+        let selection = doc.selection;
+        if (options.selection) {
+            selection = options.selection;
+        }
+        else if (options.range) {
+            selection = model.createSelection(options.range);
+        }
+        const resultRange = options.resultRange;
+        model.enqueueChange(this._buffer.batch, writer => {
+            this._buffer.lock();
+            model.deleteContent(selection);
+            if (text) {
+                model.insertContent(writer.createText(text, doc.selection.getAttributes()), selection);
+            }
+            if (resultRange) {
+                writer.setSelection(resultRange);
+            }
+            else if (!selection.is('documentSelection')) {
+                writer.setSelection(selection);
+            }
+            this._buffer.unlock();
+            this._buffer.input(textInsertions);
+        });
+    }
+}