@ckeditor/ckeditor5-engine 37.0.0-alpha.1 → 37.0.0-alpha.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-engine",
-  "version": "37.0.0-alpha.1",
+  "version": "37.0.0-alpha.3",
   "description": "The editing engine of CKEditor 5 – the best browser-based rich text editor.",
   "keywords": [
     "wysiwyg",
@@ -23,30 +23,30 @@
   ],
   "main": "src/index.js",
   "dependencies": {
-    "@ckeditor/ckeditor5-utils": "^37.0.0-alpha.1",
+    "@ckeditor/ckeditor5-utils": "^37.0.0-alpha.3",
     "lodash-es": "^4.17.15"
   },
   "devDependencies": {
-    "@ckeditor/ckeditor5-basic-styles": "^37.0.0-alpha.1",
-    "@ckeditor/ckeditor5-block-quote": "^37.0.0-alpha.1",
-    "@ckeditor/ckeditor5-clipboard": "^37.0.0-alpha.1",
-    "@ckeditor/ckeditor5-cloud-services": "^37.0.0-alpha.1",
-    "@ckeditor/ckeditor5-core": "^37.0.0-alpha.1",
-    "@ckeditor/ckeditor5-editor-classic": "^37.0.0-alpha.1",
-    "@ckeditor/ckeditor5-enter": "^37.0.0-alpha.1",
-    "@ckeditor/ckeditor5-essentials": "^37.0.0-alpha.1",
-    "@ckeditor/ckeditor5-heading": "^37.0.0-alpha.1",
-    "@ckeditor/ckeditor5-image": "^37.0.0-alpha.1",
-    "@ckeditor/ckeditor5-link": "^37.0.0-alpha.1",
-    "@ckeditor/ckeditor5-list": "^37.0.0-alpha.1",
-    "@ckeditor/ckeditor5-mention": "^37.0.0-alpha.1",
-    "@ckeditor/ckeditor5-paragraph": "^37.0.0-alpha.1",
-    "@ckeditor/ckeditor5-table": "^37.0.0-alpha.1",
-    "@ckeditor/ckeditor5-theme-lark": "^37.0.0-alpha.1",
-    "@ckeditor/ckeditor5-typing": "^37.0.0-alpha.1",
-    "@ckeditor/ckeditor5-ui": "^37.0.0-alpha.1",
-    "@ckeditor/ckeditor5-undo": "^37.0.0-alpha.1",
-    "@ckeditor/ckeditor5-widget": "^37.0.0-alpha.1",
+    "@ckeditor/ckeditor5-basic-styles": "^37.0.0-alpha.3",
+    "@ckeditor/ckeditor5-block-quote": "^37.0.0-alpha.3",
+    "@ckeditor/ckeditor5-clipboard": "^37.0.0-alpha.3",
+    "@ckeditor/ckeditor5-cloud-services": "^37.0.0-alpha.3",
+    "@ckeditor/ckeditor5-core": "^37.0.0-alpha.3",
+    "@ckeditor/ckeditor5-editor-classic": "^37.0.0-alpha.3",
+    "@ckeditor/ckeditor5-enter": "^37.0.0-alpha.3",
+    "@ckeditor/ckeditor5-essentials": "^37.0.0-alpha.3",
+    "@ckeditor/ckeditor5-heading": "^37.0.0-alpha.3",
+    "@ckeditor/ckeditor5-image": "^37.0.0-alpha.3",
+    "@ckeditor/ckeditor5-link": "^37.0.0-alpha.3",
+    "@ckeditor/ckeditor5-list": "^37.0.0-alpha.3",
+    "@ckeditor/ckeditor5-mention": "^37.0.0-alpha.3",
+    "@ckeditor/ckeditor5-paragraph": "^37.0.0-alpha.3",
+    "@ckeditor/ckeditor5-table": "^37.0.0-alpha.3",
+    "@ckeditor/ckeditor5-theme-lark": "^37.0.0-alpha.3",
+    "@ckeditor/ckeditor5-typing": "^37.0.0-alpha.3",
+    "@ckeditor/ckeditor5-ui": "^37.0.0-alpha.3",
+    "@ckeditor/ckeditor5-undo": "^37.0.0-alpha.3",
+    "@ckeditor/ckeditor5-widget": "^37.0.0-alpha.3",
     "typescript": "^4.8.4",
     "webpack": "^5.58.1",
     "webpack-cli": "^4.9.0"

package/src/view/view.d.ts

@@ -17,6 +17,7 @@ import type { StylesProcessor } from './stylesmap';
 import type Element from './element';
 import type Node from './node';
 import type Item from './item';
+type IfTrue<T> = T extends true ? true : never;
 declare const View_base: {
     new (): import("@ckeditor/ckeditor5-utils").Observable;
     prototype: import("@ckeditor/ckeditor5-utils").Observable;
@@ -183,9 +184,26 @@ export default class View extends View_base {
     enableObservers(): void;
     /**
      * Scrolls the page viewport and {@link #domRoots} with their ancestors to reveal the
-     * caret, if not already visible to the user.
-     */
-    scrollToTheSelection(): void;
+     * caret, **if not already visible to the user**.
+     *
+     * @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
+     * the viewport boundary.
+     * @param options.ancestorOffset A distance between the DOM selection and scrollable DOM root ancestor(s) to be maintained
+     * while scrolling to the selection (default is 20px). Setting this value to `0` will reveal the selection precisely at
+     * the scrollable ancestor(s) boundary.
+     * @param options.alignToTop When set `true`, the DOM selection will be aligned to the top of the viewport if not already visible
+     * (see `forceScroll` to learn more).
+     * @param options.forceScroll When set `true`, the DOM selection will be aligned to the top of the viewport and scrollable ancestors
+     * 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 ancestorOffset?: number;
+        readonly alignToTop?: T;
+        readonly forceScroll?: U;
+    }): void;
     /**
      * It will focus DOM element representing {@link module:engine/view/editableelement~EditableElement EditableElement}
      * that is currently having selection inside.

package/src/view/view.js

@@ -278,14 +278,29 @@ 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.
+     * caret, **if not already visible to the user**.
+     *
+     * @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
+     * the viewport boundary.
+     * @param options.ancestorOffset A distance between the DOM selection and scrollable DOM root ancestor(s) to be maintained
+     * while scrolling to the selection (default is 20px). Setting this value to `0` will reveal the selection precisely at
+     * the scrollable ancestor(s) boundary.
+     * @param options.alignToTop When set `true`, the DOM selection will be aligned to the top of the viewport if not already visible
+     * (see `forceScroll` to learn more).
+     * @param options.forceScroll When set `true`, the DOM selection will be aligned to the top of the viewport and scrollable ancestors
+     * whether it is already visible or not. This option will only work when `alignToTop` is `true`.
      */
-    scrollToTheSelection() {
+    scrollToTheSelection({ alignToTop, forceScroll, viewportOffset = 20, ancestorOffset = 20 } = {}) {
         const range = this.document.selection.getFirstRange();
         if (range) {
             scrollViewportToShowTarget({
                 target: this.domConverter.viewRangeToDom(range),
-                viewportOffset: 20
+                viewportOffset,
+                ancestorOffset,
+                alignToTop,
+                forceScroll
             });
         }
     }