@ckeditor/ckeditor5-engine 38.0.1 → 38.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-engine",
-  "version": "38.0.1",
+  "version": "38.1.0",
   "description": "The editing engine of CKEditor 5 – the best browser-based rich text editor.",
   "keywords": [
     "wysiwyg",
@@ -23,34 +23,9 @@
   ],
   "main": "src/index.js",
   "dependencies": {
-    "@ckeditor/ckeditor5-utils": "^38.0.1",
+    "@ckeditor/ckeditor5-utils": "38.1.0",
     "lodash-es": "^4.17.15"
   },
-  "devDependencies": {
-    "@ckeditor/ckeditor5-basic-styles": "^38.0.1",
-    "@ckeditor/ckeditor5-block-quote": "^38.0.1",
-    "@ckeditor/ckeditor5-clipboard": "^38.0.1",
-    "@ckeditor/ckeditor5-cloud-services": "^38.0.1",
-    "@ckeditor/ckeditor5-core": "^38.0.1",
-    "@ckeditor/ckeditor5-editor-classic": "^38.0.1",
-    "@ckeditor/ckeditor5-enter": "^38.0.1",
-    "@ckeditor/ckeditor5-essentials": "^38.0.1",
-    "@ckeditor/ckeditor5-heading": "^38.0.1",
-    "@ckeditor/ckeditor5-image": "^38.0.1",
-    "@ckeditor/ckeditor5-link": "^38.0.1",
-    "@ckeditor/ckeditor5-list": "^38.0.1",
-    "@ckeditor/ckeditor5-mention": "^38.0.1",
-    "@ckeditor/ckeditor5-paragraph": "^38.0.1",
-    "@ckeditor/ckeditor5-table": "^38.0.1",
-    "@ckeditor/ckeditor5-theme-lark": "^38.0.1",
-    "@ckeditor/ckeditor5-typing": "^38.0.1",
-    "@ckeditor/ckeditor5-ui": "^38.0.1",
-    "@ckeditor/ckeditor5-undo": "^38.0.1",
-    "@ckeditor/ckeditor5-widget": "^38.0.1",
-    "typescript": "^4.8.4",
-    "webpack": "^5.58.1",
-    "webpack-cli": "^4.9.0"
-  },
   "engines": {
     "node": ">=16.0.0",
     "npm": ">=5.7.1"
@@ -72,9 +47,5 @@
     "ckeditor5-metadata.json",
     "CHANGELOG.md"
   ],
-  "scripts": {
-    "build": "tsc -p ./tsconfig.json",
-    "postversion": "npm run build"
-  },
   "types": "src/index.d.ts"
 }

package/src/controller/datacontroller.js

@@ -5,7 +5,7 @@
 /**
  * @module engine/controller/datacontroller
  */
-import { CKEditorError, EmitterMixin, ObservableMixin } from '@ckeditor/ckeditor5-utils';
+import { CKEditorError, EmitterMixin, ObservableMixin, logWarning } from '@ckeditor/ckeditor5-utils';
 import Mapper from '../conversion/mapper';
 import DowncastDispatcher from '../conversion/downcastdispatcher';
 import { insertAttributesAndChildren, insertText } from '../conversion/downcasthelpers';
@@ -17,7 +17,6 @@ import ViewDowncastWriter from '../view/downcastwriter';
 import ModelRange from '../model/range';
 import { autoParagraphEmptyRoots } from '../model/utils/autoparagraphing';
 import HtmlDataProcessor from '../dataprocessor/htmldataprocessor';
-import { logWarning } from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
 /**
  * Controller for the data pipeline. The data pipeline controls how data is retrieved from the document
  * and set inside it. Hence, the controller features two methods which allow to {@link ~DataController#get get}

package/src/conversion/downcasthelpers.d.ts

@@ -236,7 +236,7 @@ export default class DowncastHelpers extends ConversionHelpers<DowncastDispatche
      * } );
      * ```
      *
-     * The `slorFor()` function can also take a callback that allows filtering which children of the model element
+     * The `createSlot()` function can also take a callback that allows filtering which children of the model element
      * should be converted into this slot.
      *
      * Imagine a table feature where for this model structure:

package/src/conversion/downcasthelpers.js

@@ -221,7 +221,7 @@ export default class DowncastHelpers extends ConversionHelpers {
      * } );
      * ```
      *
-     * The `slorFor()` function can also take a callback that allows filtering which children of the model element
+     * The `createSlot()` function can also take a callback that allows filtering which children of the model element
      * should be converted into this slot.
      *
      * Imagine a table feature where for this model structure:

package/src/conversion/upcasthelpers.js

@@ -639,8 +639,8 @@ function upcastDataToMarker(config) {
         //
         // This hack probably would not be needed if attributes are upcasted separately.
         //
-        const basePriority = priorities.get('low');
-        const maxPriority = priorities.get('highest');
+        const basePriority = priorities.low;
+        const maxPriority = priorities.highest;
         const priorityFactor = priorities.get(config.converterPriority) / maxPriority; // Number in range [ -1, 1 ].
         dispatcher.on('element', upcastAttributeToMarker(normalizedConfig), { priority: basePriority + priorityFactor });
     };

package/src/index.d.ts

@@ -73,6 +73,7 @@ export { default as ViewEmptyElement } from './view/emptyelement';
 export { default as ViewRawElement } from './view/rawelement';
 export { default as ViewUIElement } from './view/uielement';
 export { default as ViewDocumentFragment } from './view/documentfragment';
+export { default as ViewTreeWalker, type TreeWalkerValue as ViewTreeWalkerValue } from './view/treewalker';
 export type { default as ViewElementDefinition } from './view/elementdefinition';
 export type { default as ViewDocumentSelection } from './view/documentselection';
 export { default as AttributeElement } from './view/attributeelement';
@@ -103,7 +104,7 @@ export type { ViewDocumentMouseDownEvent, ViewDocumentMouseUpEvent, ViewDocument
 export type { ViewDocumentTabEvent } from './view/observer/tabobserver';
 export type { ViewDocumentClickEvent } from './view/observer/clickobserver';
 export type { ViewDocumentSelectionChangeEvent } from './view/observer/selectionobserver';
-export type { ViewRenderEvent } from './view/view';
+export type { ViewRenderEvent, ViewScrollToTheSelectionEvent } from './view/view';
 export { StylesProcessor, type BoxSides } from './view/stylesmap';
 export * from './view/styles/background';
 export * from './view/styles/border';

package/src/index.js

@@ -54,6 +54,7 @@ export { default as ViewEmptyElement } from './view/emptyelement';
 export { default as ViewRawElement } from './view/rawelement';
 export { default as ViewUIElement } from './view/uielement';
 export { default as ViewDocumentFragment } from './view/documentfragment';
+export { default as ViewTreeWalker } from './view/treewalker';
 export { default as AttributeElement } from './view/attributeelement';
 export { getFillerOffset } from './view/containerelement';
 // View / Observer.

package/src/model/documentselection.js

@@ -889,27 +889,27 @@ class LiveSelection extends Selection {
             // When gravity is overridden then don't take node before into consideration.
             if (!this.isGravityOverridden) {
                 // ...look at the node before caret and take attributes from it if it is a character node.
-                attrs = getAttrsIfCharacter(nodeBefore);
+                attrs = getTextAttributes(nodeBefore, schema);
             }
             // 3. If not, look at the node after caret...
             if (!attrs) {
-                attrs = getAttrsIfCharacter(nodeAfter);
+                attrs = getTextAttributes(nodeAfter, schema);
             }
             // 4. If not, try to find the first character on the left, that is in the same node.
             // When gravity is overridden then don't take node before into consideration.
             if (!this.isGravityOverridden && !attrs) {
                 let node = nodeBefore;
-                while (node && !schema.isInline(node) && !attrs) {
+                while (node && !attrs) {
                     node = node.previousSibling;
-                    attrs = getAttrsIfCharacter(node);
+                    attrs = getTextAttributes(node, schema);
                 }
             }
             // 5. If not found, try to find the first character on the right, that is in the same node.
             if (!attrs) {
                 let node = nodeAfter;
-                while (node && !schema.isInline(node) && !attrs) {
+                while (node && !attrs) {
                     node = node.nextSibling;
-                    attrs = getAttrsIfCharacter(node);
+                    attrs = getTextAttributes(node, schema);
                 }
             }
             // 6. If not found, selection should retrieve attributes from parent.
@@ -937,13 +937,31 @@ class LiveSelection extends Selection {
 /**
  * Helper function for {@link module:engine/model/liveselection~LiveSelection#_updateAttributes}.
  *
- * It takes model item, checks whether it is a text node (or text proxy) and, if so, returns it's attributes. If not, returns `null`.
+ * It checks if the passed model item is a text node (or text proxy) and, if so, returns it's attributes.
+ * If not, it checks if item is an inline object and does the same. Otherwise it returns `null`.
  */
-function getAttrsIfCharacter(node) {
+function getTextAttributes(node, schema) {
+    if (!node) {
+        return null;
+    }
     if (node instanceof TextProxy || node instanceof Text) {
         return node.getAttributes();
     }
-    return null;
+    if (!schema.isInline(node)) {
+        return null;
+    }
+    // Stop on inline elements (such as `<softBreak>`) that are not objects (such as `<imageInline>` or `<mathml>`).
+    if (!schema.isObject(node)) {
+        return [];
+    }
+    const attributes = [];
+    // Collect all attributes that can be applied to the text node.
+    for (const [key, value] of node.getAttributes()) {
+        if (schema.checkAttribute('$text', key)) {
+            attributes.push([key, value]);
+        }
+    }
+    return attributes;
 }
 /**
  * Removes selection attributes from element which is not empty anymore.

package/src/model/treewalker.js

@@ -126,7 +126,7 @@ export default class TreeWalker {
         // Get node just after the current position.
         // Use a highly optimized version instead of checking the text node first and then getting the node after. See #6582.
         const textNodeAtPosition = getTextNodeAtPosition(position, parent);
-        const node = textNodeAtPosition ? textNodeAtPosition : getNodeAfterPosition(position, parent, textNodeAtPosition);
+        const node = textNodeAtPosition || getNodeAfterPosition(position, parent, textNodeAtPosition);
         if (node instanceof Element) {
             if (!this.shallow) {
                 // Manual operations on path internals for optimization purposes. Here and in the rest of the method.
@@ -134,12 +134,16 @@ export default class TreeWalker {
                 this._visitedParent = node;
             }
             else {
+                // We are past the walker boundaries.
+                if (this.boundaries && this.boundaries.end.isBefore(position)) {
+                    return { done: true, value: undefined };
+                }
                 position.offset++;
             }
             this._position = position;
             return formatReturnValue('elementStart', node, previousPosition, position, 1);
         }
-        else if (node instanceof Text) {
+        if (node instanceof Text) {
             let charactersCount;
             if (this.singleCharacters) {
                 charactersCount = 1;
@@ -157,19 +161,15 @@ export default class TreeWalker {
             this._position = position;
             return formatReturnValue('text', item, previousPosition, position, charactersCount);
         }
-        else {
-            // `node` is not set, we reached the end of current `parent`.
-            position.path.pop();
-            position.offset++;
-            this._position = position;
-            this._visitedParent = parent.parent;
-            if (this.ignoreElementEnd) {
-                return this._next();
-            }
-            else {
-                return formatReturnValue('elementEnd', parent, previousPosition, position);
-            }
+        // `node` is not set, we reached the end of current `parent`.
+        position.path.pop();
+        position.offset++;
+        this._position = position;
+        this._visitedParent = parent.parent;
+        if (this.ignoreElementEnd) {
+            return this._next();
         }
+        return formatReturnValue('elementEnd', parent, previousPosition, position);
     }
     /**
      * Makes a step backward in model. Moves the {@link #position} to the previous position and returns the encountered value.
@@ -190,26 +190,22 @@ export default class TreeWalker {
         // Use a highly optimized version instead of checking the text node first and then getting the node before. See #6582.
         const positionParent = position.parent;
         const textNodeAtPosition = getTextNodeAtPosition(position, positionParent);
-        const node = textNodeAtPosition ? textNodeAtPosition : getNodeBeforePosition(position, positionParent, textNodeAtPosition);
+        const node = textNodeAtPosition || getNodeBeforePosition(position, positionParent, textNodeAtPosition);
         if (node instanceof Element) {
             position.offset--;
-            if (!this.shallow) {
-                position.path.push(node.maxOffset);
-                this._position = position;
-                this._visitedParent = node;
-                if (this.ignoreElementEnd) {
-                    return this._previous();
-                }
-                else {
-                    return formatReturnValue('elementEnd', node, previousPosition, position);
-                }
-            }
-            else {
+            if (this.shallow) {
                 this._position = position;
                 return formatReturnValue('elementStart', node, previousPosition, position, 1);
             }
+            position.path.push(node.maxOffset);
+            this._position = position;
+            this._visitedParent = node;
+            if (this.ignoreElementEnd) {
+                return this._previous();
+            }
+            return formatReturnValue('elementEnd', node, previousPosition, position);
         }
-        else if (node instanceof Text) {
+        if (node instanceof Text) {
             let charactersCount;
             if (this.singleCharacters) {
                 charactersCount = 1;
@@ -227,13 +223,11 @@ export default class TreeWalker {
             this._position = position;
             return formatReturnValue('text', item, previousPosition, position, charactersCount);
         }
-        else {
-            // `node` is not set, we reached the beginning of current `parent`.
-            position.path.pop();
-            this._position = position;
-            this._visitedParent = parent.parent;
-            return formatReturnValue('elementStart', parent, previousPosition, position, 1);
-        }
+        // `node` is not set, we reached the beginning of current `parent`.
+        position.path.pop();
+        this._position = position;
+        this._visitedParent = parent.parent;
+        return formatReturnValue('elementStart', parent, previousPosition, position, 1);
     }
 }
 function formatReturnValue(type, item, previousPosition, nextPosition, length) {

package/src/view/observer/inputobserver.js

@@ -70,8 +70,19 @@ export default class InputObserver extends DomEventObserver {
         }
         else if (domTargetRanges.length) {
             targetRanges = domTargetRanges.map(domRange => {
-                return view.domConverter.domRangeToView(domRange);
-            });
+                // Sometimes browser provides range that starts before editable node.
+                // We try to fall back to collapsed range at the valid end position.
+                // See https://github.com/ckeditor/ckeditor5/issues/14411.
+                // See https://github.com/ckeditor/ckeditor5/issues/14050.
+                const viewStart = view.domConverter.domPositionToView(domRange.startContainer, domRange.startOffset);
+                const viewEnd = view.domConverter.domPositionToView(domRange.endContainer, domRange.endOffset);
+                if (viewStart) {
+                    return view.createRange(viewStart, viewEnd);
+                }
+                else if (viewEnd) {
+                    return view.createRange(viewEnd);
+                }
+            }).filter((range) => !!range);
             // @if CK_DEBUG_TYPING // if ( ( window as any ).logCKETyping ) {
             // @if CK_DEBUG_TYPING // 	console.info( '%c[InputObserver]%c using target ranges:',
             // @if CK_DEBUG_TYPING // 		'color: green;font-weight: bold', 'font-weight:bold', targetRanges

package/src/view/styles/utils.js

@@ -7,6 +7,9 @@ const RGB_COLOR_REGEXP = /^rgb\([ ]?([0-9]{1,3}[ %]?,[ ]?){2,3}[0-9]{1,3}[ %]?\)
 const RGBA_COLOR_REGEXP = /^rgba\([ ]?([0-9]{1,3}[ %]?,[ ]?){3}(1|[0-9]+%|[0]?\.?[0-9]+)\)$/i;
 const HSL_COLOR_REGEXP = /^hsl\([ ]?([0-9]{1,3}[ %]?[,]?[ ]*){3}(1|[0-9]+%|[0]?\.?[0-9]+)?\)$/i;
 const HSLA_COLOR_REGEXP = /^hsla\([ ]?([0-9]{1,3}[ %]?,[ ]?){2,3}(1|[0-9]+%|[0]?\.?[0-9]+)\)$/i;
+// Note: This regexp hardcodes a single level of nested () for values such as `calc( var( ...) + ...)`.
+// If this gets more complex, a proper parser should be used instead.
+const CSS_SHORTHAND_VALUE_REGEXP = /\w+\((?:[^()]|\([^()]*\))*\)|\S+/gi;
 const COLOR_NAMES = new Set([
     // CSS Level 1
     'black', 'silver', 'gray', 'white', 'maroon', 'red', 'purple', 'fuchsia',
@@ -211,8 +214,6 @@ export function getPositionShorthandNormalizer(shorthand) {
  * ```
  */
 export function getShorthandValues(string) {
-    return string
-        .replace(/, /g, ',') // Exclude comma from spaces evaluation as values are separated by spaces.
-        .split(' ')
-        .map(string => string.replace(/,/g, ', ')); // Restore original notation.
+    const matches = string.matchAll(CSS_SHORTHAND_VALUE_REGEXP);
+    return Array.from(matches).map(i => i[0]);
 }

package/src/view/treewalker.js

@@ -136,36 +136,38 @@ export default class TreeWalker {
                 position = new Position(node, 0);
             }
             else {
+                // We are past the walker boundaries.
+                if (this.boundaries && this.boundaries.end.isBefore(position)) {
+                    return { done: true, value: undefined };
+                }
                 position.offset++;
             }
             this._position = position;
             return this._formatReturnValue('elementStart', node, previousPosition, position, 1);
         }
-        else if (node instanceof Text) {
+        if (node instanceof Text) {
             if (this.singleCharacters) {
                 position = new Position(node, 0);
                 this._position = position;
                 return this._next();
             }
+            let charactersCount = node.data.length;
+            let item;
+            // If text stick out of walker range, we need to cut it and wrap in TextProxy.
+            if (node == this._boundaryEndParent) {
+                charactersCount = this.boundaries.end.offset;
+                item = new TextProxy(node, 0, charactersCount);
+                position = Position._createAfter(item);
+            }
             else {
-                let charactersCount = node.data.length;
-                let item;
-                // If text stick out of walker range, we need to cut it and wrap in TextProxy.
-                if (node == this._boundaryEndParent) {
-                    charactersCount = this.boundaries.end.offset;
-                    item = new TextProxy(node, 0, charactersCount);
-                    position = Position._createAfter(item);
-                }
-                else {
-                    item = new TextProxy(node, 0, node.data.length);
-                    // If not just keep moving forward.
-                    position.offset++;
-                }
-                this._position = position;
-                return this._formatReturnValue('text', item, previousPosition, position, charactersCount);
+                item = new TextProxy(node, 0, node.data.length);
+                // If not just keep moving forward.
+                position.offset++;
             }
+            this._position = position;
+            return this._formatReturnValue('text', item, previousPosition, position, charactersCount);
         }
-        else if (typeof node == 'string') {
+        if (typeof node == 'string') {
             let textLength;
             if (this.singleCharacters) {
                 textLength = 1;
@@ -180,17 +182,13 @@ export default class TreeWalker {
             this._position = position;
             return this._formatReturnValue('text', textProxy, previousPosition, position, textLength);
         }
-        else {
-            // `node` is not set, we reached the end of current `parent`.
-            position = Position._createAfter(parent);
-            this._position = position;
-            if (this.ignoreElementEnd) {
-                return this._next();
-            }
-            else {
-                return this._formatReturnValue('elementEnd', parent, previousPosition, position);
-            }
+        // `node` is not set, we reached the end of current `parent`.
+        position = Position._createAfter(parent);
+        this._position = position;
+        if (this.ignoreElementEnd) {
+            return this._next();
         }
+        return this._formatReturnValue('elementEnd', parent, previousPosition, position);
     }
     /**
      * Makes a step backward in view. Moves the {@link #position} to the previous position and returns the encountered value.
@@ -222,48 +220,42 @@ export default class TreeWalker {
             node = parent.getChild(position.offset - 1);
         }
         if (node instanceof Element) {
-            if (!this.shallow) {
-                position = new Position(node, node.childCount);
-                this._position = position;
-                if (this.ignoreElementEnd) {
-                    return this._previous();
-                }
-                else {
-                    return this._formatReturnValue('elementEnd', node, previousPosition, position);
-                }
-            }
-            else {
+            if (this.shallow) {
                 position.offset--;
                 this._position = position;
                 return this._formatReturnValue('elementStart', node, previousPosition, position, 1);
             }
+            position = new Position(node, node.childCount);
+            this._position = position;
+            if (this.ignoreElementEnd) {
+                return this._previous();
+            }
+            return this._formatReturnValue('elementEnd', node, previousPosition, position);
         }
-        else if (node instanceof Text) {
+        if (node instanceof Text) {
             if (this.singleCharacters) {
                 position = new Position(node, node.data.length);
                 this._position = position;
                 return this._previous();
             }
+            let charactersCount = node.data.length;
+            let item;
+            // If text stick out of walker range, we need to cut it and wrap in TextProxy.
+            if (node == this._boundaryStartParent) {
+                const offset = this.boundaries.start.offset;
+                item = new TextProxy(node, offset, node.data.length - offset);
+                charactersCount = item.data.length;
+                position = Position._createBefore(item);
+            }
             else {
-                let charactersCount = node.data.length;
-                let item;
-                // If text stick out of walker range, we need to cut it and wrap in TextProxy.
-                if (node == this._boundaryStartParent) {
-                    const offset = this.boundaries.start.offset;
-                    item = new TextProxy(node, offset, node.data.length - offset);
-                    charactersCount = item.data.length;
-                    position = Position._createBefore(item);
-                }
-                else {
-                    item = new TextProxy(node, 0, node.data.length);
-                    // If not just keep moving backward.
-                    position.offset--;
-                }
-                this._position = position;
-                return this._formatReturnValue('text', item, previousPosition, position, charactersCount);
+                item = new TextProxy(node, 0, node.data.length);
+                // If not just keep moving backward.
+                position.offset--;
             }
+            this._position = position;
+            return this._formatReturnValue('text', item, previousPosition, position, charactersCount);
         }
-        else if (typeof node == 'string') {
+        if (typeof node == 'string') {
             let textLength;
             if (!this.singleCharacters) {
                 // Check if text stick out of walker range.
@@ -278,12 +270,10 @@ export default class TreeWalker {
             this._position = position;
             return this._formatReturnValue('text', textProxy, previousPosition, position, textLength);
         }
-        else {
-            // `node` is not set, we reached the beginning of current `parent`.
-            position = Position._createBefore(parent);
-            this._position = position;
-            return this._formatReturnValue('elementStart', parent, previousPosition, position, 1);
-        }
+        // `node` is not set, we reached the beginning of current `parent`.
+        position = Position._createBefore(parent);
+        this._position = position;
+        return this._formatReturnValue('elementStart', parent, previousPosition, position, 1);
     }
     /**
      * Format returned data and adjust `previousPosition` and `nextPosition` if reach the bound of the {@link module:engine/view/text~Text}.

package/src/view/view.d.ts

@@ -18,6 +18,7 @@ import type Element from './element';
 import type Node from './node';
 import type Item from './item';
 type IfTrue<T> = T extends true ? true : never;
+type DomRange = globalThis.Range;
 declare const View_base: {
     new (): import("@ckeditor/ckeditor5-utils").Observable;
     prototype: import("@ckeditor/ckeditor5-utils").Observable;
@@ -186,6 +187,9 @@ export default class View extends View_base {
      * Scrolls the page viewport and {@link #domRoots} with their ancestors to reveal the
      * caret, **if not already visible to the user**.
      *
+     * **Note**: Calling this method fires the {@link module:engine/view/view~ViewScrollToTheSelectionEvent} event that
+     * allows custom behaviors.
+     *
      * @param options Additional configuration of the scrolling behavior.
      * @param options.viewportOffset A distance between the DOM selection and the viewport boundary to be maintained
      * while scrolling to the selection (default is 20px). Setting this value to `0` will reveal the selection precisely at
@@ -199,7 +203,12 @@ export default class View extends View_base {
      * whether it is already visible or not. This option will only work when `alignToTop` is `true`.
      */
     scrollToTheSelection<T extends boolean, U extends IfTrue<T>>({ alignToTop, forceScroll, viewportOffset, ancestorOffset }?: {
-        readonly viewportOffset?: number;
+        readonly viewportOffset?: number | {
+            top: number;
+            bottom: number;
+            left: number;
+            right: number;
+        };
         readonly ancestorOffset?: number;
         readonly alignToTop?: T;
         readonly forceScroll?: U;
@@ -432,4 +441,40 @@ export type ViewRenderEvent = {
     name: 'render';
     args: [];
 };
+/**
+ * An event fired at the moment of {@link module:engine/view/view~View#scrollToTheSelection} being called. It
+ * carries two objects in its payload (`args`):
+ *
+ * * The first argument is the {@link module:engine/view/view~ViewScrollToTheSelectionEventData object containing data} that gets
+ *   passed down to the {@link module:utils/dom/scroll~scrollViewportToShowTarget} helper. If some event listener modifies it, it can
+ *   adjust the behavior of the scrolling (e.g. include additional `viewportOffset`).
+ * * The second argument corresponds to the original arguments passed to {@link module:utils/dom/scroll~scrollViewportToShowTarget}.
+ *   It allows listeners to re-execute the `scrollViewportToShowTarget()` method with its original arguments if there is such a need,
+ *   for instance, if the integration requires re–scrolling after certain interaction.
+ *
+ * @eventName ~View#scrollToTheSelection
+ */
+export type ViewScrollToTheSelectionEvent = {
+    name: 'scrollToTheSelection';
+    args: [
+        ViewScrollToTheSelectionEventData,
+        Parameters<View['scrollToTheSelection']>[0]
+    ];
+};
+/**
+ * An object passed down to the {@link module:utils/dom/scroll~scrollViewportToShowTarget} helper while calling
+ * {@link module:engine/view/view~View#scrollToTheSelection}.
+ */
+export type ViewScrollToTheSelectionEventData = {
+    target: DomRange;
+    viewportOffset: {
+        top: number;
+        bottom: number;
+        left: number;
+        right: number;
+    };
+    ancestorOffset: number;
+    alignToTop?: boolean;
+    forceScroll?: boolean;
+};
 export {};

package/src/view/view.js

@@ -24,6 +24,7 @@ import TabObserver from './observer/tabobserver';
 import { CKEditorError, ObservableMixin, scrollViewportToShowTarget } from '@ckeditor/ckeditor5-utils';
 import { injectUiElementHandling } from './uielement';
 import { injectQuirksHandling } from './filler';
+import { cloneDeep } from 'lodash-es';
 /**
  * Editor's view controller class. Its main responsibility is DOM - View management for editing purposes, to provide
  * abstraction over the DOM structure and events and hide all browsers quirks.
@@ -283,6 +284,9 @@ export default class View extends ObservableMixin() {
      * Scrolls the page viewport and {@link #domRoots} with their ancestors to reveal the
      * caret, **if not already visible to the user**.
      *
+     * **Note**: Calling this method fires the {@link module:engine/view/view~ViewScrollToTheSelectionEvent} event that
+     * allows custom behaviors.
+     *
      * @param options Additional configuration of the scrolling behavior.
      * @param options.viewportOffset A distance between the DOM selection and the viewport boundary to be maintained
      * while scrolling to the selection (default is 20px). Setting this value to `0` will reveal the selection precisely at
@@ -297,15 +301,28 @@ export default class View extends ObservableMixin() {
      */
     scrollToTheSelection({ alignToTop, forceScroll, viewportOffset = 20, ancestorOffset = 20 } = {}) {
         const range = this.document.selection.getFirstRange();
-        if (range) {
-            scrollViewportToShowTarget({
-                target: this.domConverter.viewRangeToDom(range),
-                viewportOffset,
-                ancestorOffset,
-                alignToTop,
-                forceScroll
-            });
+        if (!range) {
+            return;
+        }
+        // Clone to make sure properties like `viewportOffset` are not mutated in the event listeners.
+        const originalArgs = cloneDeep({ alignToTop, forceScroll, viewportOffset, ancestorOffset });
+        if (typeof viewportOffset === 'number') {
+            viewportOffset = {
+                top: viewportOffset,
+                bottom: viewportOffset,
+                left: viewportOffset,
+                right: viewportOffset
+            };
         }
+        const options = {
+            target: this.domConverter.viewRangeToDom(range),
+            viewportOffset,
+            ancestorOffset,
+            alignToTop,
+            forceScroll
+        };
+        this.fire('scrollToTheSelection', options, originalArgs);
+        scrollViewportToShowTarget(options);
     }
     /**
      * It will focus DOM element representing {@link module:engine/view/editableelement~EditableElement EditableElement}