@ckeditor/ckeditor5-typing 41.4.1 → 42.0.0-alpha.0

package/dist/index.js

@@ -11,6 +11,8 @@ import { escapeRegExp } from 'lodash-es';
  * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */ /**
+ * @module typing/utils/changebuffer
+ */ /**
  * Change buffer allows to group atomic changes (like characters that have been typed) into
  * {@link module:engine/model/batch~Batch batches}.
  *
@@ -30,9 +32,58 @@ import { escapeRegExp } from 'lodash-es';
  * ```
  */ class ChangeBuffer {
     /**
-     * The current batch to which a feature should add its operations. Once the {@link #size}
-     * is reached or exceeds the {@link #limit}, the batch is set to a new instance and the size is reset.
-     */ get batch() {
+	 * The model instance.
+	 */ model;
+    /**
+	 * The maximum number of atomic changes which can be contained in one batch.
+	 */ limit;
+    /**
+	 * Whether the buffer is locked. A locked buffer cannot be reset unless it gets unlocked.
+	 */ _isLocked;
+    /**
+	 * The number of atomic changes in the buffer. Once it exceeds the {@link #limit},
+	 * the {@link #batch batch} is set to a new one.
+	 */ _size;
+    /**
+	 * The current batch instance.
+	 */ _batch = null;
+    /**
+	 * The callback to document the change event which later needs to be removed.
+	 */ _changeCallback;
+    /**
+	 * The callback to document selection `change:attribute` and `change:range` events which resets the buffer.
+	 */ _selectionChangeCallback;
+    /**
+	 * Creates a new instance of the change buffer.
+	 *
+	 * @param limit The maximum number of atomic changes which can be contained in one batch.
+	 */ constructor(model, limit = 20){
+        this.model = model;
+        this._size = 0;
+        this.limit = limit;
+        this._isLocked = false;
+        // The function to be called in order to notify the buffer about batches which appeared in the document.
+        // The callback will check whether it is a new batch and in that case the buffer will be flushed.
+        //
+        // The reason why the buffer needs to be flushed whenever a new batch appears is that the changes added afterwards
+        // should be added to a new batch. For instance, when the user types, then inserts an image, and then types again,
+        // the characters typed after inserting the image should be added to a different batch than the characters typed before.
+        this._changeCallback = (evt, batch)=>{
+            if (batch.isLocal && batch.isUndoable && batch !== this._batch) {
+                this._reset(true);
+            }
+        };
+        this._selectionChangeCallback = ()=>{
+            this._reset();
+        };
+        this.model.document.on('change', this._changeCallback);
+        this.model.document.selection.on('change:range', this._selectionChangeCallback);
+        this.model.document.selection.on('change:attribute', this._selectionChangeCallback);
+    }
+    /**
+	 * The current batch to which a feature should add its operations. Once the {@link #size}
+	 * is reached or exceeds the {@link #limit}, the batch is set to a new instance and the size is reset.
+	 */ get batch() {
         if (!this._batch) {
             this._batch = this.model.createBatch({
                 isTyping: true
@@ -41,106 +92,92 @@ import { escapeRegExp } from 'lodash-es';
         return this._batch;
     }
     /**
-     * The number of atomic changes in the buffer. Once it exceeds the {@link #limit},
-     * the {@link #batch batch} is set to a new one.
-     */ get size() {
+	 * The number of atomic changes in the buffer. Once it exceeds the {@link #limit},
+	 * the {@link #batch batch} is set to a new one.
+	 */ get size() {
         return this._size;
     }
     /**
-     * The input number of changes into the buffer. Once the {@link #size} is
-     * reached or exceeds the {@link #limit}, the batch is set to a new instance and the size is reset.
-     *
-     * @param changeCount The number of atomic changes to input.
-     */ input(changeCount) {
+	 * The input number of changes into the buffer. Once the {@link #size} is
+	 * reached or exceeds the {@link #limit}, the batch is set to a new instance and the size is reset.
+	 *
+	 * @param changeCount The number of atomic changes to input.
+	 */ input(changeCount) {
         this._size += changeCount;
         if (this._size >= this.limit) {
             this._reset(true);
         }
     }
     /**
-     * Whether the buffer is locked. A locked buffer cannot be reset unless it gets unlocked.
-     */ get isLocked() {
+	 * Whether the buffer is locked. A locked buffer cannot be reset unless it gets unlocked.
+	 */ get isLocked() {
         return this._isLocked;
     }
     /**
-     * Locks the buffer.
-     */ lock() {
+	 * Locks the buffer.
+	 */ lock() {
         this._isLocked = true;
     }
     /**
-     * Unlocks the buffer.
-     */ unlock() {
+	 * Unlocks the buffer.
+	 */ unlock() {
         this._isLocked = false;
     }
     /**
-     * Destroys the buffer.
-     */ destroy() {
+	 * Destroys the buffer.
+	 */ destroy() {
         this.model.document.off('change', this._changeCallback);
         this.model.document.selection.off('change:range', this._selectionChangeCallback);
         this.model.document.selection.off('change:attribute', this._selectionChangeCallback);
     }
     /**
-     * Resets the change buffer.
-     *
-     * @param ignoreLock Whether internal lock {@link #isLocked} should be ignored.
-     */ _reset(ignoreLock = false) {
+	 * Resets the change buffer.
+	 *
+	 * @param ignoreLock Whether internal lock {@link #isLocked} should be ignored.
+	 */ _reset(ignoreLock = false) {
         if (!this.isLocked || ignoreLock) {
             this._batch = null;
             this._size = 0;
         }
     }
-    /**
-     * Creates a new instance of the change buffer.
-     *
-     * @param limit The maximum number of atomic changes which can be contained in one batch.
-     */ constructor(model, limit = 20){
-        /**
-         * The current batch instance.
-         */ this._batch = null;
-        this.model = model;
-        this._size = 0;
-        this.limit = limit;
-        this._isLocked = false;
-        // The function to be called in order to notify the buffer about batches which appeared in the document.
-        // The callback will check whether it is a new batch and in that case the buffer will be flushed.
-        //
-        // The reason why the buffer needs to be flushed whenever a new batch appears is that the changes added afterwards
-        // should be added to a new batch. For instance, when the user types, then inserts an image, and then types again,
-        // the characters typed after inserting the image should be added to a different batch than the characters typed before.
-        this._changeCallback = (evt, batch)=>{
-            if (batch.isLocal && batch.isUndoable && batch !== this._batch) {
-                this._reset(true);
-            }
-        };
-        this._selectionChangeCallback = ()=>{
-            this._reset();
-        };
-        this.model.document.on('change', this._changeCallback);
-        this.model.document.selection.on('change:range', this._selectionChangeCallback);
-        this.model.document.selection.on('change:attribute', this._selectionChangeCallback);
-    }
 }
 
-class InsertTextCommand extends Command {
+/**
+ * The insert text command. Used by the {@link module:typing/input~Input input feature} to handle typing.
+ */ class InsertTextCommand extends Command {
+    /**
+	 * Typing's change buffer used to group subsequent changes into batches.
+	 */ _buffer;
+    /**
+	 * Creates an instance of the command.
+	 *
+	 * @param undoStepSize The maximum number of atomic changes
+	 * which can be contained in one batch in the command buffer.
+	 */ constructor(editor, undoStepSize){
+        super(editor);
+        this._buffer = new ChangeBuffer(editor.model, undoStepSize);
+        // Since this command may execute on different selectable than selection, it should be checked directly in execute block.
+        this._isEnabledBasedOnSelection = false;
+    }
     /**
-     * The current change buffer.
-     */ get buffer() {
+	 * The current change buffer.
+	 */ get buffer() {
         return this._buffer;
     }
     /**
-     * @inheritDoc
-     */ destroy() {
+	 * @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 options The command options.
-     */ execute(options = {}) {
+	 * 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 options The command options.
+	 */ execute(options = {}) {
         const model = this.editor.model;
         const doc = model.document;
         const text = options.text || '';
@@ -174,17 +211,6 @@ class InsertTextCommand extends Command {
             this._buffer.input(textInsertions);
         });
     }
-    /**
-     * Creates an instance of the command.
-     *
-     * @param undoStepSize The maximum number of atomic changes
-     * which can be contained in one batch in the command buffer.
-     */ constructor(editor, undoStepSize){
-        super(editor);
-        this._buffer = new ChangeBuffer(editor.model, undoStepSize);
-        // Since this command may execute on different selectable than selection, it should be checked directly in execute block.
-        this._isEnabledBasedOnSelection = false;
-    }
 }
 
 const TYPING_INPUT_TYPES = [
@@ -199,16 +225,16 @@ const TYPING_INPUT_TYPES = [
     // This one is used by Safari when accepting spell check suggestions from the autocorrection pop-up (Mac).
     'insertReplacementText'
 ];
-class InsertTextObserver extends Observer {
-    /**
-     * @inheritDoc
-     */ observe() {}
+/**
+ * Text insertion observer introduces the {@link module:engine/view/document~Document#event:insertText} event.
+ */ class InsertTextObserver extends Observer {
     /**
-     * @inheritDoc
-     */ stopObserving() {}
+	 * Instance of the focus observer. Insert text observer calls
+	 * {@link module:engine/view/observer/focusobserver~FocusObserver#flush} to mark the latest focus change as complete.
+	 */ focusObserver;
     /**
-     * @inheritDoc
-     */ constructor(view){
+	 * @inheritDoc
+	 */ constructor(view){
         super(view);
         this.focusObserver = view.getObserver(FocusObserver);
         // On Android composition events should immediately be applied to the model. Rendering is not disabled.
@@ -281,17 +307,25 @@ class InsertTextObserver extends Observer {
             priority: 'lowest'
         });
     }
+    /**
+	 * @inheritDoc
+	 */ observe() {}
+    /**
+	 * @inheritDoc
+	 */ stopObserving() {}
 }
 
-class Input extends Plugin {
+/**
+ * Handles text input coming from the keyboard or other input methods.
+ */ class Input extends Plugin {
     /**
-     * @inheritDoc
-     */ static get pluginName() {
+	 * @inheritDoc
+	 */ static get pluginName() {
         return 'Input';
     }
     /**
-     * @inheritDoc
-     */ init() {
+	 * @inheritDoc
+	 */ init() {
         const editor = this.editor;
         const model = editor.model;
         const view = editor.editing.view;
@@ -407,23 +441,45 @@ function deleteSelectionContent(model, insertTextCommand) {
     buffer.unlock();
 }
 
-class DeleteCommand extends Command {
+/**
+ * The delete command. Used by the {@link module:typing/delete~Delete delete feature} to handle the <kbd>Delete</kbd> and
+ * <kbd>Backspace</kbd> keys.
+ */ class DeleteCommand extends Command {
     /**
-     * The current change buffer.
-     */ get buffer() {
+	 * The directionality of the delete describing in what direction it should
+	 * consume the content when the selection is collapsed.
+	 */ direction;
+    /**
+	 * Delete's change buffer used to group subsequent changes into batches.
+	 */ _buffer;
+    /**
+	 * Creates an instance of the command.
+	 *
+	 * @param direction The directionality of the delete describing in what direction it
+	 * should consume the content when the selection is collapsed.
+	 */ constructor(editor, direction){
+        super(editor);
+        this.direction = direction;
+        this._buffer = new ChangeBuffer(editor.model, editor.config.get('typing.undoStep'));
+        // Since this command may execute on different selectable than selection, it should be checked directly in execute block.
+        this._isEnabledBasedOnSelection = false;
+    }
+    /**
+	 * The current change buffer.
+	 */ get buffer() {
         return this._buffer;
     }
     /**
-     * Executes the delete command. Depending on whether the selection is collapsed or not, deletes its content
-     * or a piece of content in the {@link #direction defined direction}.
-     *
-     * @fires execute
-     * @param options The command options.
-     * @param options.unit See {@link module:engine/model/utils/modifyselection~modifySelection}'s options.
-     * @param options.sequence A number describing which subsequent delete event it is without the key being released.
-     * See the {@link module:engine/view/document~Document#event:delete} event data.
-     * @param options.selection Selection to remove. If not set, current model selection will be used.
-     */ execute(options = {}) {
+	 * Executes the delete command. Depending on whether the selection is collapsed or not, deletes its content
+	 * or a piece of content in the {@link #direction defined direction}.
+	 *
+	 * @fires execute
+	 * @param options The command options.
+	 * @param options.unit See {@link module:engine/model/utils/modifyselection~modifySelection}'s options.
+	 * @param options.sequence A number describing which subsequent delete event it is without the key being released.
+	 * See the {@link module:engine/view/document~Document#event:delete} event data.
+	 * @param options.selection Selection to remove. If not set, current model selection will be used.
+	 */ execute(options = {}) {
         const model = this.editor.model;
         const doc = model.document;
         model.enqueueChange(this._buffer.batch, (writer)=>{
@@ -489,21 +545,21 @@ class DeleteCommand extends Command {
         });
     }
     /**
-     * If the user keeps <kbd>Backspace</kbd> or <kbd>Delete</kbd> key pressed, the content of the current
-     * editable will be cleared. However, this will not yet lead to resetting the remaining block to a paragraph
-     * (which happens e.g. when the user does <kbd>Ctrl</kbd> + <kbd>A</kbd>, <kbd>Backspace</kbd>).
-     *
-     * But, if the user pressed the key in an empty editable for the first time,
-     * we want to replace the entire content with a paragraph if:
-     *
-     * * the current limit element is empty,
-     * * the paragraph is allowed in the limit element,
-     * * the limit doesn't already have a paragraph inside.
-     *
-     * See https://github.com/ckeditor/ckeditor5-typing/issues/61.
-     *
-     * @param sequence A number describing which subsequent delete event it is without the key being released.
-     */ _shouldEntireContentBeReplacedWithParagraph(sequence) {
+	 * If the user keeps <kbd>Backspace</kbd> or <kbd>Delete</kbd> key pressed, the content of the current
+	 * editable will be cleared. However, this will not yet lead to resetting the remaining block to a paragraph
+	 * (which happens e.g. when the user does <kbd>Ctrl</kbd> + <kbd>A</kbd>, <kbd>Backspace</kbd>).
+	 *
+	 * But, if the user pressed the key in an empty editable for the first time,
+	 * we want to replace the entire content with a paragraph if:
+	 *
+	 * * the current limit element is empty,
+	 * * the paragraph is allowed in the limit element,
+	 * * the limit doesn't already have a paragraph inside.
+	 *
+	 * See https://github.com/ckeditor/ckeditor5-typing/issues/61.
+	 *
+	 * @param sequence A number describing which subsequent delete event it is without the key being released.
+	 */ _shouldEntireContentBeReplacedWithParagraph(sequence) {
         // Does nothing if user pressed and held the "Backspace" or "Delete" key.
         if (sequence > 1) {
             return false;
@@ -531,10 +587,10 @@ class DeleteCommand extends Command {
         return true;
     }
     /**
-     * The entire content is replaced with the paragraph. Selection is moved inside the paragraph.
-     *
-     * @param writer The model writer.
-     */ _replaceEntireContentWithParagraph(writer) {
+	 * The entire content is replaced with the paragraph. Selection is moved inside the paragraph.
+	 *
+	 * @param writer The model writer.
+	 */ _replaceEntireContentWithParagraph(writer) {
         const model = this.editor.model;
         const doc = model.document;
         const selection = doc.selection;
@@ -545,12 +601,12 @@ class DeleteCommand extends Command {
         writer.setSelection(paragraph, 0);
     }
     /**
-     * Checks if the selection is inside an empty element that is the first child of the limit element
-     * and should be replaced with a paragraph.
-     *
-     * @param selection The selection.
-     * @param sequence A number describing which subsequent delete event it is without the key being released.
-     */ _shouldReplaceFirstBlockWithParagraph(selection, sequence) {
+	 * Checks if the selection is inside an empty element that is the first child of the limit element
+	 * and should be replaced with a paragraph.
+	 *
+	 * @param selection The selection.
+	 * @param sequence A number describing which subsequent delete event it is without the key being released.
+	 */ _shouldReplaceFirstBlockWithParagraph(selection, sequence) {
         const model = this.editor.model;
         // Does nothing if user pressed and held the "Backspace" key or it was a "Delete" button.
         if (sequence > 1 || this.direction != 'backward') {
@@ -581,18 +637,6 @@ class DeleteCommand extends Command {
         }
         return true;
     }
-    /**
-     * Creates an instance of the command.
-     *
-     * @param direction The directionality of the delete describing in what direction it
-     * should consume the content when the selection is collapsed.
-     */ constructor(editor, direction){
-        super(editor);
-        this.direction = direction;
-        this._buffer = new ChangeBuffer(editor.model, editor.config.get('typing.undoStep'));
-        // Since this command may execute on different selectable than selection, it should be checked directly in execute block.
-        this._isEnabledBasedOnSelection = false;
-    }
 }
 
 const DELETE_CHARACTER = 'character';
@@ -680,16 +724,12 @@ const DELETE_EVENT_TYPES = {
         direction: DELETE_FORWARD
     }
 };
-class DeleteObserver extends Observer {
-    /**
-     * @inheritDoc
-     */ observe() {}
-    /**
-     * @inheritDoc
-     */ stopObserving() {}
+/**
+ * Delete observer introduces the {@link module:engine/view/document~Document#event:delete} event.
+ */ class DeleteObserver extends Observer {
     /**
-     * @inheritDoc
-     */ constructor(view){
+	 * @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
@@ -748,6 +788,12 @@ class DeleteObserver extends Observer {
             enableChromeWorkaround(this);
         }
     }
+    /**
+	 * @inheritDoc
+	 */ observe() {}
+    /**
+	 * @inheritDoc
+	 */ stopObserving() {}
 }
 /**
  * Enables workaround for the issue https://github.com/ckeditor/ckeditor5/issues/11904.
@@ -832,15 +878,21 @@ class DeleteObserver extends Observer {
     return false;
 }
 
-class Delete extends Plugin {
+/**
+ * The delete and backspace feature. Handles keys such as <kbd>Delete</kbd> and <kbd>Backspace</kbd>, other
+ * keystrokes and user actions that result in deleting content in the editor.
+ */ class Delete extends Plugin {
+    /**
+	 * Whether pressing backspace should trigger undo action
+	 */ _undoOnBackspace;
     /**
-     * @inheritDoc
-     */ static get pluginName() {
+	 * @inheritDoc
+	 */ static get pluginName() {
         return 'Delete';
     }
     /**
-     * @inheritDoc
-     */ init() {
+	 * @inheritDoc
+	 */ init() {
         const editor = this.editor;
         const view = editor.editing.view;
         const viewDocument = view.document;
@@ -893,17 +945,22 @@ class Delete extends Plugin {
         }
     }
     /**
-     * If the next user action after calling this method is pressing backspace, it would undo the last change.
-     *
-     * Requires {@link module:undo/undoediting~UndoEditing} plugin. If not loaded, does nothing.
-     */ requestUndoOnBackspace() {
+	 * If the next user action after calling this method is pressing backspace, it would undo the last change.
+	 *
+	 * Requires {@link module:undo/undoediting~UndoEditing} plugin. If not loaded, does nothing.
+	 */ requestUndoOnBackspace() {
         if (this.editor.plugins.has('UndoEditing')) {
             this._undoOnBackspace = true;
         }
     }
 }
 
-class Typing extends Plugin {
+/**
+ * The typing feature. It handles typing.
+ *
+ * This is a "glue" plugin which loads the {@link module:typing/input~Input} and {@link module:typing/delete~Delete}
+ * plugins.
+ */ class Typing extends Plugin {
     static get requires() {
         return [
             Input,
@@ -911,8 +968,8 @@ class Typing extends Plugin {
         ];
     }
     /**
-     * @inheritDoc
-     */ static get pluginName() {
+	 * @inheritDoc
+	 */ static get pluginName() {
         return 'Typing';
     }
 }
@@ -921,6 +978,8 @@ class Typing extends Plugin {
  * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */ /**
+ * @module typing/utils/getlasttextline
+ */ /**
  * Returns the last text line from the given range.
  *
  * "The last text line" is understood as text (from one or more text nodes) which is limited either by a parent block
@@ -964,15 +1023,57 @@ class Typing extends Plugin {
     };
 }
 
-class TextWatcher extends ObservableMixin() {
+/**
+ * The text watcher feature.
+ *
+ * Fires the {@link module:typing/textwatcher~TextWatcher#event:matched:data `matched:data`},
+ * {@link module:typing/textwatcher~TextWatcher#event:matched:selection `matched:selection`} and
+ * {@link module:typing/textwatcher~TextWatcher#event:unmatched `unmatched`} events on typing or selection changes.
+ */ class TextWatcher extends /* #__PURE__ */ ObservableMixin() {
+    /**
+	 * The editor's model.
+	 */ model;
+    /**
+	 * The function used to match the text.
+	 *
+	 * The test callback can return 3 values:
+	 *
+	 * * `false` if there is no match,
+	 * * `true` if there is a match,
+	 * * an object if there is a match and we want to pass some additional information to the {@link #event:matched:data} event.
+	 */ testCallback;
+    /**
+	 * Whether there is a match currently.
+	 */ _hasMatch;
+    /**
+	 * Creates a text watcher instance.
+	 *
+	 * @param testCallback See {@link module:typing/textwatcher~TextWatcher#testCallback}.
+	 */ constructor(model, testCallback){
+        super();
+        this.model = model;
+        this.testCallback = testCallback;
+        this._hasMatch = false;
+        this.set('isEnabled', true);
+        // Toggle text watching on isEnabled state change.
+        this.on('change:isEnabled', ()=>{
+            if (this.isEnabled) {
+                this._startListening();
+            } else {
+                this.stopListening(model.document.selection);
+                this.stopListening(model.document);
+            }
+        });
+        this._startListening();
+    }
     /**
-     * Flag indicating whether there is a match currently.
-     */ get hasMatch() {
+	 * Flag indicating whether there is a match currently.
+	 */ get hasMatch() {
         return this._hasMatch;
     }
     /**
-     * Starts listening to the editor for typing and selection events.
-     */ _startListening() {
+	 * Starts listening to the editor for typing and selection events.
+	 */ _startListening() {
         const model = this.model;
         const document = model.document;
         this.listenTo(document.selection, 'change:range', (evt, { directChange })=>{
@@ -1000,15 +1101,15 @@ class TextWatcher extends ObservableMixin() {
         });
     }
     /**
-     * Checks the editor content for matched text.
-     *
-     * @fires matched:data
-     * @fires matched:selection
-     * @fires unmatched
-     *
-     * @param suffix A suffix used for generating the event name.
-     * @param data Data object for event.
-     */ _evaluateTextBeforeSelection(suffix, data = {}) {
+	 * Checks the editor content for matched text.
+	 *
+	 * @fires matched:data
+	 * @fires matched:selection
+	 * @fires unmatched
+	 *
+	 * @param suffix A suffix used for generating the event name.
+	 * @param data Data object for event.
+	 */ _evaluateTextBeforeSelection(suffix, data = {}) {
         const model = this.model;
         const document = model.document;
         const selection = document.selection;
@@ -1031,38 +1132,158 @@ class TextWatcher extends ObservableMixin() {
             this.fire(`matched:${suffix}`, eventData);
         }
     }
-    /**
-     * Creates a text watcher instance.
-     *
-     * @param testCallback See {@link module:typing/textwatcher~TextWatcher#testCallback}.
-     */ constructor(model, testCallback){
-        super();
-        this.model = model;
-        this.testCallback = testCallback;
-        this._hasMatch = false;
-        this.set('isEnabled', true);
-        // Toggle text watching on isEnabled state change.
-        this.on('change:isEnabled', ()=>{
-            if (this.isEnabled) {
-                this._startListening();
-            } else {
-                this.stopListening(model.document.selection);
-                this.stopListening(model.document);
-            }
-        });
-        this._startListening();
-    }
 }
 
-class TwoStepCaretMovement extends Plugin {
+/**
+ * This plugin enables the two-step caret (phantom) movement behavior for
+ * {@link module:typing/twostepcaretmovement~TwoStepCaretMovement#registerAttribute registered attributes}
+ * on arrow right (<kbd>→</kbd>) and left (<kbd>←</kbd>) key press.
+ *
+ * Thanks to this (phantom) caret movement the user is able to type before/after as well as at the
+ * beginning/end of an attribute.
+ *
+ * **Note:** This plugin support right–to–left (Arabic, Hebrew, etc.) content by mirroring its behavior
+ * but for the sake of simplicity examples showcase only left–to–right use–cases.
+ *
+ * # Forward movement
+ *
+ * ## "Entering" an attribute:
+ *
+ * When this plugin is enabled and registered for the `a` attribute and the selection is right before it
+ * (at the attribute boundary), pressing the right arrow key will not move the selection but update its
+ * attributes accordingly:
+ *
+ * * When enabled:
+ *
+ * ```xml
+ * foo{}<$text a="true">bar</$text>
+ * ```
+ *
+ * 	<kbd>→</kbd>
+ *
+ * ```xml
+ * foo<$text a="true">{}bar</$text>
+ * ```
+ *
+ * * When disabled:
+ *
+ * ```xml
+ * foo{}<$text a="true">bar</$text>
+ * ```
+ *
+ * 	<kbd>→</kbd>
+ *
+ * ```xml
+ * foo<$text a="true">b{}ar</$text>
+ * ```
+ *
+ *
+ * ## "Leaving" an attribute:
+ *
+ * * When enabled:
+ *
+ * ```xml
+ * <$text a="true">bar{}</$text>baz
+ * ```
+ *
+ * 	<kbd>→</kbd>
+ *
+ * ```xml
+ * <$text a="true">bar</$text>{}baz
+ * ```
+ *
+ * * When disabled:
+ *
+ * ```xml
+ * <$text a="true">bar{}</$text>baz
+ * ```
+ *
+ * 	<kbd>→</kbd>
+ *
+ * ```xml
+ * <$text a="true">bar</$text>b{}az
+ * ```
+ *
+ * # Backward movement
+ *
+ * * When enabled:
+ *
+ * ```xml
+ * <$text a="true">bar</$text>{}baz
+ * ```
+ *
+ * 	<kbd>←</kbd>
+ *
+ * ```xml
+ * <$text a="true">bar{}</$text>baz
+ * ```
+ *
+ * * When disabled:
+ *
+ * ```xml
+ * <$text a="true">bar</$text>{}baz
+ * ```
+ *
+ * 	<kbd>←</kbd>
+ *
+ * ```xml
+ * <$text a="true">ba{}r</$text>b{}az
+ * ```
+ *
+ * # Multiple attributes
+ *
+ * * When enabled and many attributes starts or ends at the same position:
+ *
+ * ```xml
+ * <$text a="true" b="true">bar</$text>{}baz
+ * ```
+ *
+ * 	<kbd>←</kbd>
+ *
+ * ```xml
+ * <$text a="true" b="true">bar{}</$text>baz
+ * ```
+ *
+ * * When enabled and one procedes another:
+ *
+ * ```xml
+ * <$text a="true">bar</$text><$text b="true">{}bar</$text>
+ * ```
+ *
+ * 	<kbd>←</kbd>
+ *
+ * ```xml
+ * <$text a="true">bar{}</$text><$text b="true">bar</$text>
+ * ```
+ *
+ */ class TwoStepCaretMovement extends Plugin {
+    /**
+	 * A set of attributes to handle.
+	 */ attributes;
     /**
-     * @inheritDoc
-     */ static get pluginName() {
+	 * The current UID of the overridden gravity, as returned by
+	 * {@link module:engine/model/writer~Writer#overrideSelectionGravity}.
+	 */ _overrideUid;
+    /**
+	 * A flag indicating that the automatic gravity restoration should not happen upon the next
+	 * gravity restoration.
+	 * {@link module:engine/model/selection~Selection#event:change:range} event.
+	 */ _isNextGravityRestorationSkipped = false;
+    /**
+	 * @inheritDoc
+	 */ static get pluginName() {
         return 'TwoStepCaretMovement';
     }
     /**
-     * @inheritDoc
-     */ init() {
+	 * @inheritDoc
+	 */ constructor(editor){
+        super(editor);
+        this.attributes = new Set();
+        this._overrideUid = null;
+    }
+    /**
+	 * @inheritDoc
+	 */ init() {
         const editor = this.editor;
         const model = editor.model;
         const view = editor.editing.view;
@@ -1131,19 +1352,19 @@ class TwoStepCaretMovement extends Plugin {
         this._handleDeleteContentAfterNode();
     }
     /**
-     * Registers a given attribute for the two-step caret movement.
-     *
-     * @param attribute Name of the attribute to handle.
-     */ registerAttribute(attribute) {
+	 * Registers a given attribute for the two-step caret movement.
+	 *
+	 * @param attribute Name of the attribute to handle.
+	 */ registerAttribute(attribute) {
         this.attributes.add(attribute);
     }
     /**
-     * Updates the document selection and the view according to the two–step caret movement state
-     * when moving **forwards**. Executed upon `keypress` in the {@link module:engine/view/view~View}.
-     *
-     * @param data Data of the key press.
-     * @returns `true` when the handler prevented caret movement.
-     */ _handleForwardMovement(data) {
+	 * Updates the document selection and the view according to the two–step caret movement state
+	 * when moving **forwards**. Executed upon `keypress` in the {@link module:engine/view/view~View}.
+	 *
+	 * @param data Data of the key press.
+	 * @returns `true` when the handler prevented caret movement.
+	 */ _handleForwardMovement(data) {
         const attributes = this.attributes;
         const model = this.editor.model;
         const selection = model.document.selection;
@@ -1194,12 +1415,12 @@ class TwoStepCaretMovement extends Plugin {
         return false;
     }
     /**
-     * Updates the document selection and the view according to the two–step caret movement state
-     * when moving **backwards**. Executed upon `keypress` in the {@link module:engine/view/view~View}.
-     *
-     * @param data Data of the key press.
-     * @returns `true` when the handler prevented caret movement
-     */ _handleBackwardMovement(data) {
+	 * Updates the document selection and the view according to the two–step caret movement state
+	 * when moving **backwards**. Executed upon `keypress` in the {@link module:engine/view/view~View}.
+	 *
+	 * @param data Data of the key press.
+	 * @returns `true` when the handler prevented caret movement
+	 */ _handleBackwardMovement(data) {
         const attributes = this.attributes;
         const model = this.editor.model;
         const selection = model.document.selection;
@@ -1283,14 +1504,14 @@ class TwoStepCaretMovement extends Plugin {
         return false;
     }
     /**
-     * Starts listening to {@link module:engine/view/document~Document#event:mousedown} and
-     * {@link module:engine/view/document~Document#event:selectionChange} and puts the selection before/after a 2-step node
-     * if clicked at the beginning/ending of the 2-step node.
-     *
-     * The purpose of this action is to allow typing around the 2-step node directly after a click.
-     *
-     * See https://github.com/ckeditor/ckeditor5/issues/1016.
-     */ _enableClickingAfterNode() {
+	 * Starts listening to {@link module:engine/view/document~Document#event:mousedown} and
+	 * {@link module:engine/view/document~Document#event:selectionChange} and puts the selection before/after a 2-step node
+	 * if clicked at the beginning/ending of the 2-step node.
+	 *
+	 * The purpose of this action is to allow typing around the 2-step node directly after a click.
+	 *
+	 * See https://github.com/ckeditor/ckeditor5/issues/1016.
+	 */ _enableClickingAfterNode() {
         const editor = this.editor;
         const model = editor.model;
         const selection = model.document.selection;
@@ -1333,14 +1554,14 @@ class TwoStepCaretMovement extends Plugin {
         });
     }
     /**
-     * Starts listening to {@link module:engine/model/model~Model#event:insertContent} and corrects the model
-     * selection attributes if the selection is at the end of a two-step node after inserting the content.
-     *
-     * The purpose of this action is to improve the overall UX because the user is no longer "trapped" by the
-     * two-step attribute of the selection, and they can type a "clean" (`linkHref`–less) text right away.
-     *
-     * See https://github.com/ckeditor/ckeditor5/issues/6053.
-     */ _enableInsertContentSelectionAttributesFixer() {
+	 * Starts listening to {@link module:engine/model/model~Model#event:insertContent} and corrects the model
+	 * selection attributes if the selection is at the end of a two-step node after inserting the content.
+	 *
+	 * The purpose of this action is to improve the overall UX because the user is no longer "trapped" by the
+	 * two-step attribute of the selection, and they can type a "clean" (`linkHref`–less) text right away.
+	 *
+	 * See https://github.com/ckeditor/ckeditor5/issues/6053.
+	 */ _enableInsertContentSelectionAttributesFixer() {
         const editor = this.editor;
         const model = editor.model;
         const selection = model.document.selection;
@@ -1355,17 +1576,17 @@ class TwoStepCaretMovement extends Plugin {
         });
     }
     /**
-     * Starts listening to {@link module:engine/model/model~Model#deleteContent} and checks whether
-     * removing a content right after the tow-step attribute.
-     *
-     * If so, the selection should not preserve the two-step attribute. However, if
-     * the {@link module:typing/twostepcaretmovement~TwoStepCaretMovement} plugin is active and
-     * the selection has the two-step attribute due to overridden gravity (at the end), the two-step attribute should stay untouched.
-     *
-     * The purpose of this action is to allow removing the link text and keep the selection outside the link.
-     *
-     * See https://github.com/ckeditor/ckeditor5/issues/7521.
-     */ _handleDeleteContentAfterNode() {
+	 * Starts listening to {@link module:engine/model/model~Model#deleteContent} and checks whether
+	 * removing a content right after the tow-step attribute.
+	 *
+	 * If so, the selection should not preserve the two-step attribute. However, if
+	 * the {@link module:typing/twostepcaretmovement~TwoStepCaretMovement} plugin is active and
+	 * the selection has the two-step attribute due to overridden gravity (at the end), the two-step attribute should stay untouched.
+	 *
+	 * The purpose of this action is to allow removing the link text and keep the selection outside the link.
+	 *
+	 * See https://github.com/ckeditor/ckeditor5/issues/7521.
+	 */ _handleDeleteContentAfterNode() {
         const editor = this.editor;
         const model = editor.model;
         const selection = model.document.selection;
@@ -1415,42 +1636,30 @@ class TwoStepCaretMovement extends Plugin {
         });
     }
     /**
-     * `true` when the gravity is overridden for the plugin.
-     */ get _isGravityOverridden() {
+	 * `true` when the gravity is overridden for the plugin.
+	 */ get _isGravityOverridden() {
         return !!this._overrideUid;
     }
     /**
-     * Overrides the gravity using the {@link module:engine/model/writer~Writer model writer}
-     * and stores the information about this fact in the {@link #_overrideUid}.
-     *
-     * A shorthand for {@link module:engine/model/writer~Writer#overrideSelectionGravity}.
-     */ _overrideGravity() {
+	 * Overrides the gravity using the {@link module:engine/model/writer~Writer model writer}
+	 * and stores the information about this fact in the {@link #_overrideUid}.
+	 *
+	 * A shorthand for {@link module:engine/model/writer~Writer#overrideSelectionGravity}.
+	 */ _overrideGravity() {
         this._overrideUid = this.editor.model.change((writer)=>{
             return writer.overrideSelectionGravity();
         });
     }
     /**
-     * Restores the gravity using the {@link module:engine/model/writer~Writer model writer}.
-     *
-     * A shorthand for {@link module:engine/model/writer~Writer#restoreSelectionGravity}.
-     */ _restoreGravity() {
+	 * Restores the gravity using the {@link module:engine/model/writer~Writer model writer}.
+	 *
+	 * A shorthand for {@link module:engine/model/writer~Writer#restoreSelectionGravity}.
+	 */ _restoreGravity() {
         this.editor.model.change((writer)=>{
             writer.restoreSelectionGravity(this._overrideUid);
             this._overrideUid = null;
         });
     }
-    /**
-     * @inheritDoc
-     */ constructor(editor){
-        super(editor);
-        /**
-         * A flag indicating that the automatic gravity restoration should not happen upon the next
-         * gravity restoration.
-         * {@link module:engine/model/selection~Selection#event:change:range} event.
-         */ this._isNextGravityRestorationSkipped = false;
-        this.attributes = new Set();
-        this._overrideUid = null;
-    }
 }
 /**
  * Checks whether the selection has any of given attributes.
@@ -1715,23 +1924,35 @@ const DEFAULT_TRANSFORMATIONS = [
     'typography',
     'quotes'
 ];
-class TextTransformation extends Plugin {
+/**
+ * The text transformation plugin.
+ */ class TextTransformation extends Plugin {
     /**
-     * @inheritDoc
-     */ static get requires() {
+	 * @inheritDoc
+	 */ static get requires() {
         return [
             'Delete',
             'Input'
         ];
     }
     /**
-     * @inheritDoc
-     */ static get pluginName() {
+	 * @inheritDoc
+	 */ static get pluginName() {
         return 'TextTransformation';
     }
     /**
-     * @inheritDoc
-     */ init() {
+	 * @inheritDoc
+	 */ constructor(editor){
+        super(editor);
+        editor.config.define('typing', {
+            transformations: {
+                include: DEFAULT_TRANSFORMATIONS
+            }
+        });
+    }
+    /**
+	 * @inheritDoc
+	 */ init() {
         const model = this.editor.model;
         const modelSelection = model.document.selection;
         modelSelection.on('change:range', ()=>{
@@ -1741,8 +1962,8 @@ class TextTransformation extends Plugin {
         this._enableTransformationWatchers();
     }
     /**
-     * Create new TextWatcher listening to the editor for typing and selection events.
-     */ _enableTransformationWatchers() {
+	 * Create new TextWatcher listening to the editor for typing and selection events.
+	 */ _enableTransformationWatchers() {
         const editor = this.editor;
         const model = editor.model;
         const deletePlugin = editor.plugins.get('Delete');
@@ -1789,16 +2010,6 @@ class TextTransformation extends Plugin {
         });
         watcher.bind('isEnabled').to(this);
     }
-    /**
-     * @inheritDoc
-     */ constructor(editor){
-        super(editor);
-        editor.config.define('typing', {
-            transformations: {
-                include: DEFAULT_TRANSFORMATIONS
-            }
-        });
-    }
 }
 /**
  * Normalizes the configuration `from` parameter value.
@@ -1876,6 +2087,8 @@ class TextTransformation extends Plugin {
  * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */ /**
+ * @module typing/utils/findattributerange
+ */ /**
  * Returns a model range that covers all consecutive nodes with the same `attributeName` and its `value`
  * that intersect the given `position`.
  *