@ckeditor/ckeditor5-fullscreen 45.0.0 → 45.1.0-alpha.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-fullscreen",
-  "version": "45.0.0",
+  "version": "45.1.0-alpha.1",
   "description": "Fullscreen mode feature for CKEditor 5.",
   "keywords": [
     "ckeditor",
@@ -13,18 +13,13 @@
   "type": "module",
   "main": "src/index.js",
   "dependencies": {
-    "@ckeditor/ckeditor5-comments": "45.0.0",
-    "@ckeditor/ckeditor5-core": "45.0.0",
-    "@ckeditor/ckeditor5-document-outline": "45.0.0",
-    "@ckeditor/ckeditor5-editor-classic": "45.0.0",
-    "@ckeditor/ckeditor5-editor-decoupled": "45.0.0",
-    "@ckeditor/ckeditor5-icons": "45.0.0",
-    "@ckeditor/ckeditor5-pagination": "45.0.0",
-    "@ckeditor/ckeditor5-real-time-collaboration": "45.0.0",
-    "@ckeditor/ckeditor5-revision-history": "45.0.0",
-    "@ckeditor/ckeditor5-ui": "45.0.0",
-    "@ckeditor/ckeditor5-utils": "45.0.0",
-    "ckeditor5": "45.0.0"
+    "@ckeditor/ckeditor5-core": "45.1.0-alpha.1",
+    "@ckeditor/ckeditor5-editor-classic": "45.1.0-alpha.1",
+    "@ckeditor/ckeditor5-editor-decoupled": "45.1.0-alpha.1",
+    "@ckeditor/ckeditor5-icons": "45.1.0-alpha.1",
+    "@ckeditor/ckeditor5-ui": "45.1.0-alpha.1",
+    "@ckeditor/ckeditor5-utils": "45.1.0-alpha.1",
+    "ckeditor5": "45.1.0-alpha.1"
   },
   "author": "CKSource (http://cksource.com/)",
   "license": "SEE LICENSE IN LICENSE.md",

package/src/fullscreencommand.d.ts

@@ -6,6 +6,7 @@
  * @module fullscreen/fullscreencommand
  */
 import { Command, type Editor } from 'ckeditor5/src/core.js';
+import AbstractEditorHandler from './handlers/abstracteditorhandler.js';
 /**
  * A command toggling the fullscreen mode.
  */
@@ -19,8 +20,21 @@ export default class FullscreenCommand extends Command {
     value: boolean;
     /**
      * Specialized class handling the fullscreen mode toggling for a specific editor type.
+     *
+     * If you want to add support for a new editor type (for now, only Classic and Decoupled editors are handled),
+     * create a custom handler that extends `AbstractEditorHandler` and replace `fullscreenHandler` with it after editor initialization:
+     *
+     * ```ts
+     * // See the details of how to implement a custom handler in the `AbstractEditorHandler` class API docs.
+     * class CustomEditorHandler extends AbstractEditorHandler {}
+     *
+     * CustomEditorClass.create( document.querySelector( '#editor' ), {} )
+     * 	.then( ( editor ) => {
+     * 		editor.commands.get( 'toggleFullscreen' ).fullscreenHandler = new CustomEditorHandler( editor );
+     * 	} );
+     * ```
      */
-    private _fullscreenHandler;
+    fullscreenHandler: AbstractEditorHandler;
     /**
      * @inheritDoc
      */

package/src/fullscreencommand.js

@@ -6,8 +6,6 @@
  * @module fullscreen/fullscreencommand
  */
 import { Command } from 'ckeditor5/src/core.js';
-import { ClassicEditor } from '@ckeditor/ckeditor5-editor-classic';
-import { DecoupledEditor } from '@ckeditor/ckeditor5-editor-decoupled';
 import AbstractEditorHandler from './handlers/abstracteditorhandler.js';
 import ClassicEditorHandler from './handlers/classiceditorhandler.js';
 import DecoupledEditorHandler from './handlers/decouplededitorhandler.js';
@@ -17,8 +15,21 @@ import DecoupledEditorHandler from './handlers/decouplededitorhandler.js';
 export default class FullscreenCommand extends Command {
     /**
      * Specialized class handling the fullscreen mode toggling for a specific editor type.
+     *
+     * If you want to add support for a new editor type (for now, only Classic and Decoupled editors are handled),
+     * create a custom handler that extends `AbstractEditorHandler` and replace `fullscreenHandler` with it after editor initialization:
+     *
+     * ```ts
+     * // See the details of how to implement a custom handler in the `AbstractEditorHandler` class API docs.
+     * class CustomEditorHandler extends AbstractEditorHandler {}
+     *
+     * CustomEditorClass.create( document.querySelector( '#editor' ), {} )
+     * 	.then( ( editor ) => {
+     * 		editor.commands.get( 'toggleFullscreen' ).fullscreenHandler = new CustomEditorHandler( editor );
+     * 	} );
+     * ```
      */
-    _fullscreenHandler;
+    fullscreenHandler;
     /**
      * @inheritDoc
      */
@@ -28,16 +39,16 @@ export default class FullscreenCommand extends Command {
         this.isEnabled = true;
         this.value = false;
         // Choose the appropriate handler based on the editor type.
-        // Currently only ClassicEditor and DecoupledEditor are supported. For other editor types, the abstract handler is used
-        // which will throw if user tries to enable the fullscreen mode.
-        if (editor instanceof ClassicEditor) {
-            this._fullscreenHandler = new ClassicEditorHandler(editor);
+        // Currently only `ClassicEditor` and `DecoupledEditor` are supported. For other editor types, you should create a custom handler
+        // that extends `AbstractEditorHandler` and replace `fullscreenHandler` with it.
+        if (isClassicEditor(editor)) {
+            this.fullscreenHandler = new ClassicEditorHandler(editor);
         }
-        else if (editor instanceof DecoupledEditor) {
-            this._fullscreenHandler = new DecoupledEditorHandler(editor);
+        else if (isDecoupledEditor(editor)) {
+            this.fullscreenHandler = new DecoupledEditorHandler(editor);
         }
         else {
-            this._fullscreenHandler = new AbstractEditorHandler(editor);
+            this.fullscreenHandler = new AbstractEditorHandler(editor);
         }
     }
     /**
@@ -55,14 +66,26 @@ export default class FullscreenCommand extends Command {
      * Enables the fullscreen mode.
      */
     _enableFullscreenMode() {
-        this._fullscreenHandler.enable();
+        this.fullscreenHandler.enable();
         this.value = true;
     }
     /**
      * Disables the fullscreen mode.
      */
     _disableFullscreenMode() {
-        this._fullscreenHandler.disable();
+        this.fullscreenHandler.disable();
         this.value = false;
     }
 }
+/**
+ * Classic editor typeguard.
+ */
+function isClassicEditor(editor) {
+    return editor.constructor.editorName === 'ClassicEditor';
+}
+/**
+ * Decoupled editor typeguard.
+ */
+function isDecoupledEditor(editor) {
+    return editor.constructor.editorName === 'DecoupledEditor';
+}

package/src/handlers/abstracteditorhandler.d.ts

@@ -4,9 +4,65 @@
  */
 import { type EventInfo } from 'ckeditor5/src/utils.js';
 import type { ElementApi, Editor, EditorConfig } from 'ckeditor5/src/core.js';
-import type { RevisionViewerEditor } from '@ckeditor/ckeditor5-revision-history';
 /**
- * The abstract editor type handler. It should be extended by the particular editor type handler.
+ * The abstract editor type handler.
+ *
+ * This class defines some actions and behaviors that are applied when fullscreen mode is toggled, and which are common
+ * regardless of the editor type. Then, specific classes like `ClassicEditorHandler` or `DecoupledEditorHandler`
+ * extend this class with actions specific for these editor types.
+ *
+ * Extend this class to provide fullscreen mode handling for unsupported editor types,
+ * or if you wish to heavily customize the default behavior.
+ *
+ * The only method that is necessary to provide when extending this class is {@link #defaultOnEnter}. However, make sure to
+ * familiarize yourself with the below full list of actions taken by `AbstractEditorHandler` to understand what is covered by default,
+ * and what should be provided by you.
+ *
+ * When entering the fullscreen mode, the {@link #enable} method is called. It creates the properly styled container
+ * and handles the editor features that need it, in the following order:
+ *
+ * 1. Saves the scroll positions of all ancestors of the editable element to restore them after leaving the fullscreen mode.
+ * 2. Executes the {@link #defaultOnEnter} method to move the proper editor UI elements to the fullscreen mode.
+ * **If you extend the abstract handler, you should override this method** to move the elements that are specific to your editor type, like:
+ * 	editable, toolbar, menu bar.
+ * 	Use {@link #moveToFullscreen} method for this purpose to ensure they are automatically cleaned up after leaving the fullscreen mode.
+ * 3. Adds proper classes to the `<body>` and `<html>` elements to block page scrolling, adjust `z-index` etc.
+ * 4. Changes the position of some dialogs to utilize the empty space on the right side of the editable element.
+ *
+ * Steps 5-11 are only executed if the corresponding features are used.
+ *
+ * 5. If presence list is used, moves it to the fullscreen mode container.
+ * 6. If document outline is used, moves it to the fullscreen mode.
+ * 7. If pagination is used, adjusts it's configuration for the changed view.
+ * 8. If annotations are used, moves them to the fullscreen mode.
+ * 9. If revision history is used, overrides the callbacks to show the revision viewer in the fullscreen mode.
+ * 10. If source editing and document outline are both used, hides the document outline header.
+ * 11. If custom container is used, hides all other elements in it to ensure they don't create an empty unscrollable space.
+ *
+ * Then finally:
+ *
+ * 12. Executes the configured {@link module:fullscreen/fullscreenconfig~FullscreenConfig#onEnterCallback
+ * 	`config.fullscreen.onEnterCallback`} function.
+ * 	By default, it returns the fullscreen mode container element so it can be further customized.
+ *
+ * When leaving the fullscreen mode, the {@link #disable} method is called. It does the following:
+ *
+ * 1. Execute the configured {@link module:fullscreen/fullscreenconfig~FullscreenConfig#onLeaveCallback
+ * 	`config.fullscreen.onLeaveCallback`} function.
+ * 2. Remove the classes added to the `<body>` and `<html>` elements.
+ * 3. If document outline is used, restore its default container.
+ * 4. If annotations are used, restore their original state (UI, filters etc).
+ * 5. If revision history is used, restore the original callbacks.
+ * 6. If source editing and document outline are both used, restore the document outline header.
+ * 7. Restore all moved elements to their original place.
+ * 8. Destroy the fullscreen mode container.
+ * 9. If the editor has a toolbar, switch its behavior to the one configured in the
+ * 	{@link module:ui/toolbar/toolbarview~ToolbarOptions#shouldGroupWhenFull} property.
+ * 10. Restore the scroll positions of all ancestors of the editable element.
+ * 11. If pagination is used, restore its default configuration.
+ * 12. Restore default dialogs positions.
+ *
+ * This class is exported to allow for custom extensions.
  */
 export default class AbstractEditorHandler {
     /**
@@ -48,11 +104,11 @@ export default class AbstractEditorHandler {
     /**
      * A callback that shows the revision viewer, stored to restore the original one after exiting the fullscreen mode.
      */
-    protected _showRevisionViewerCallback: ((config?: EditorConfig) => Promise<RevisionViewerEditor | null>) | null;
+    protected _showRevisionViewerCallback: ((config?: EditorConfig) => Promise<any>) | null;
     /**
      * A callback that closes the revision viewer, stored to restore the original one after exiting the fullscreen mode.
      */
-    protected _closeRevisionViewerCallback: ((viewerEditor?: RevisionViewerEditor) => Promise<unknown>) | null;
+    protected _closeRevisionViewerCallback: ((viewerEditor?: any) => Promise<unknown>) | null;
     /**
      * An editor instance. It should be set by the particular editor type handler.
      */
@@ -91,7 +147,7 @@ export default class AbstractEditorHandler {
      * Returns the fullscreen mode container element so it can be further customized via
      * `fullscreen.onEnterCallback` configuration property.
      */
-    protected _defaultOnEnter(): HTMLElement;
+    defaultOnEnter(): HTMLElement;
     /**
      * Destroys the fullscreen mode container.
      */

package/src/handlers/abstracteditorhandler.js

@@ -9,7 +9,64 @@ import { BodyCollection, DialogViewPosition } from 'ckeditor5/src/ui.js';
 import { global, createElement, Rect } from 'ckeditor5/src/utils.js';
 const DIALOG_OFFSET = 28;
 /**
- * The abstract editor type handler. It should be extended by the particular editor type handler.
+ * The abstract editor type handler.
+ *
+ * This class defines some actions and behaviors that are applied when fullscreen mode is toggled, and which are common
+ * regardless of the editor type. Then, specific classes like `ClassicEditorHandler` or `DecoupledEditorHandler`
+ * extend this class with actions specific for these editor types.
+ *
+ * Extend this class to provide fullscreen mode handling for unsupported editor types,
+ * or if you wish to heavily customize the default behavior.
+ *
+ * The only method that is necessary to provide when extending this class is {@link #defaultOnEnter}. However, make sure to
+ * familiarize yourself with the below full list of actions taken by `AbstractEditorHandler` to understand what is covered by default,
+ * and what should be provided by you.
+ *
+ * When entering the fullscreen mode, the {@link #enable} method is called. It creates the properly styled container
+ * and handles the editor features that need it, in the following order:
+ *
+ * 1. Saves the scroll positions of all ancestors of the editable element to restore them after leaving the fullscreen mode.
+ * 2. Executes the {@link #defaultOnEnter} method to move the proper editor UI elements to the fullscreen mode.
+ * **If you extend the abstract handler, you should override this method** to move the elements that are specific to your editor type, like:
+ * 	editable, toolbar, menu bar.
+ * 	Use {@link #moveToFullscreen} method for this purpose to ensure they are automatically cleaned up after leaving the fullscreen mode.
+ * 3. Adds proper classes to the `<body>` and `<html>` elements to block page scrolling, adjust `z-index` etc.
+ * 4. Changes the position of some dialogs to utilize the empty space on the right side of the editable element.
+ *
+ * Steps 5-11 are only executed if the corresponding features are used.
+ *
+ * 5. If presence list is used, moves it to the fullscreen mode container.
+ * 6. If document outline is used, moves it to the fullscreen mode.
+ * 7. If pagination is used, adjusts it's configuration for the changed view.
+ * 8. If annotations are used, moves them to the fullscreen mode.
+ * 9. If revision history is used, overrides the callbacks to show the revision viewer in the fullscreen mode.
+ * 10. If source editing and document outline are both used, hides the document outline header.
+ * 11. If custom container is used, hides all other elements in it to ensure they don't create an empty unscrollable space.
+ *
+ * Then finally:
+ *
+ * 12. Executes the configured {@link module:fullscreen/fullscreenconfig~FullscreenConfig#onEnterCallback
+ * 	`config.fullscreen.onEnterCallback`} function.
+ * 	By default, it returns the fullscreen mode container element so it can be further customized.
+ *
+ * When leaving the fullscreen mode, the {@link #disable} method is called. It does the following:
+ *
+ * 1. Execute the configured {@link module:fullscreen/fullscreenconfig~FullscreenConfig#onLeaveCallback
+ * 	`config.fullscreen.onLeaveCallback`} function.
+ * 2. Remove the classes added to the `<body>` and `<html>` elements.
+ * 3. If document outline is used, restore its default container.
+ * 4. If annotations are used, restore their original state (UI, filters etc).
+ * 5. If revision history is used, restore the original callbacks.
+ * 6. If source editing and document outline are both used, restore the document outline header.
+ * 7. Restore all moved elements to their original place.
+ * 8. Destroy the fullscreen mode container.
+ * 9. If the editor has a toolbar, switch its behavior to the one configured in the
+ * 	{@link module:ui/toolbar/toolbarview~ToolbarOptions#shouldGroupWhenFull} property.
+ * 10. Restore the scroll positions of all ancestors of the editable element.
+ * 11. If pagination is used, restore its default configuration.
+ * 12. Restore default dialogs positions.
+ *
+ * This class is exported to allow for custom extensions.
  */
 export default class AbstractEditorHandler {
     /**
@@ -111,7 +168,7 @@ export default class AbstractEditorHandler {
             this._wrapper = createElement(this._document, 'div', {
                 class: 'ck ck-fullscreen__main-wrapper'
             });
-            // For now, the container is generated in a very straightforward way. If necessary, it may be rewritten using our UI lib.
+            // For now, the container is generated in a very straightforward way. If necessary, it may be rewritten using editor's UI lib.
             this._wrapper.innerHTML = `
 				<div class="ck ck-fullscreen__top-wrapper ck-reset_all">
 					<div class="ck ck-fullscreen__menu-bar" data-ck-fullscreen="menu-bar"></div>
@@ -139,7 +196,7 @@ export default class AbstractEditorHandler {
      */
     enable() {
         this._saveAncestorsScrollPositions(this._editor.ui.getEditableElement());
-        this._defaultOnEnter();
+        this.defaultOnEnter();
         // Block scroll if the fullscreen container is the body element. Otherwise the document has to stay scrollable.
         if (this._editor.config.get('fullscreen.container') === this._document.body) {
             this._document.body.classList.add('ck-fullscreen');
@@ -232,15 +289,21 @@ export default class AbstractEditorHandler {
         for (const placeholderName of this._placeholderMap.keys()) {
             this.restoreMovedElementLocation(placeholderName);
         }
-        this._editor.ui.view.toolbar.switchBehavior(this._editor.config.get('toolbar.shouldNotGroupWhenFull') === true ? 'static' : 'dynamic');
-        if (this._placeholderMap.size === 0) {
-            this._destroyContainer();
+        // Container is also destroyed in the `restoreMovedElementLocation()` method, but we need to do it here
+        // to ensure that the container is destroyed even if no elements were moved.
+        this._destroyContainer();
+        if (this._editor.ui.view.toolbar) {
+            this._editor.ui.view.toolbar.switchBehavior(this._editor.config.get('toolbar.shouldNotGroupWhenFull') === true ? 'static' : 'dynamic');
         }
         // Restore scroll positions of all ancestors. It may include the closest editable wrapper causing the editor to change
         // the visible content, which is not what we want. Thus, after executing the command, we use
         // `editor.editing.view.scrollToTheSelection()` to scroll the editor viewport to the current selection.
+        // Using `behavior: 'instant'` is necessary to force scroll if some of the containers has `scroll-behavior: smooth` set (otherwise
+        // the scroll won't happen).
         for (const [ancestor, value] of this._savedAncestorsScrollPositions) {
-            ancestor.scrollTo(value.scrollLeft, value.scrollTop);
+            // `ScrollBehavior` has incorrect type definition in currently used TS version (5.0.4). Fix should be present since 5.1.0:
+            // https://github.com/Microsoft/TypeScript/issues/28755. Hence we need a type assertion here.
+            ancestor.scrollTo({ left: value.scrollLeft, top: value.scrollTop, behavior: 'instant' });
         }
         this._savedAncestorsScrollPositions.clear();
         // Pagination has to be restored after leaving fullscreen mode to ensure proper rendering.
@@ -276,7 +339,7 @@ export default class AbstractEditorHandler {
      * Returns the fullscreen mode container element so it can be further customized via
      * `fullscreen.onEnterCallback` configuration property.
      */
-    _defaultOnEnter() {
+    defaultOnEnter() {
         return this.getWrapper();
     }
     /**
@@ -376,7 +439,7 @@ export default class AbstractEditorHandler {
         // If no filter is defined for `wideSidebar`, read the filters for the active display(s) mode and apply them.
         // It's possible there are filters for both `narrowSidebar` and `inline` modes, so display annotations that match any of them.
         else if (annotationsFilters.size) {
-            annotationsUIs.activate('wideSidebar', annotation => [...annotationsFilters.values()].some(filter => filter(annotation)));
+            annotationsUIs.activate('wideSidebar', (annotation) => [...annotationsFilters.values()].some(filter => filter(annotation)));
         }
         // If no filters are defined for the active display mode(s), simply display all annotations in the wide sidebar.
         else {

package/src/handlers/classiceditorhandler.d.ts

@@ -19,5 +19,5 @@ export default class ClassicEditorHandler extends AbstractEditorHandler {
     /**
      * A function that moves the editor UI elements to the fullscreen mode.
      */
-    protected _defaultOnEnter(): HTMLElement;
+    defaultOnEnter(): HTMLElement;
 }

package/src/handlers/classiceditorhandler.js

@@ -25,7 +25,7 @@ export default class ClassicEditorHandler extends AbstractEditorHandler {
     /**
      * A function that moves the editor UI elements to the fullscreen mode.
      */
-    _defaultOnEnter() {
+    defaultOnEnter() {
         const editorUI = this._editor.ui;
         const editorUIView = editorUI.view;
         // Code coverage is provided in the commercial package repository as integration unit tests.

package/src/handlers/decouplededitorhandler.d.ts

@@ -22,5 +22,5 @@ export default class DecoupledEditorHandler extends AbstractEditorHandler {
     /**
      * A function that moves the editor UI elements to the fullscreen mode.
      */
-    protected _defaultOnEnter(): HTMLElement;
+    defaultOnEnter(): HTMLElement;
 }

package/src/handlers/decouplededitorhandler.js

@@ -21,7 +21,7 @@ export default class DecoupledEditorHandler extends AbstractEditorHandler {
     /**
      * A function that moves the editor UI elements to the fullscreen mode.
      */
-    _defaultOnEnter() {
+    defaultOnEnter() {
         // Code coverage is provided in the commercial package repository as integration unit tests.
         /* istanbul ignore next -- @preserve */
         if (this._editor.plugins.has('Pagination') && this._editor.plugins.get('Pagination').isEnabled) {

package/src/index.d.ts

@@ -8,6 +8,7 @@
 export { default as Fullscreen } from './fullscreen.js';
 export { default as FullscreenEditing } from './fullscreenediting.js';
 export { default as FullscreenUI } from './fullscreenui.js';
+export { default as AbstractEditorHandler } from './handlers/abstracteditorhandler.js';
 export type { default as FullscreenConfig } from './fullscreenconfig.js';
 export type { default as FullscreenCommand } from './fullscreencommand.js';
 import './augmentation.js';

package/src/index.js

@@ -8,4 +8,5 @@
 export { default as Fullscreen } from './fullscreen.js';
 export { default as FullscreenEditing } from './fullscreenediting.js';
 export { default as FullscreenUI } from './fullscreenui.js';
+export { default as AbstractEditorHandler } from './handlers/abstracteditorhandler.js';
 import './augmentation.js';

package/theme/fullscreen.css

@@ -102,7 +102,6 @@ Fullscreen layout:
 
 .ck-fullscreen__main-wrapper .ck-fullscreen__editable {
 	margin-top: var(--ck-fullscreen-editor-top-margin);
-	margin-bottom: 56px;
 	height: 100%;
 	margin-left: auto;
 
@@ -115,9 +114,11 @@ Fullscreen layout:
 
 .ck-fullscreen__main-wrapper .ck-fullscreen__editable .ck.ck-editor__editable:not(.ck-editor__nested-editable) {
 	box-sizing: border-box;
-	width: calc(210mm + 2px);
+	width: calc(210mm + 2px); /* Make sure the border is taken into account. */
+	max-width: calc(210mm + 2px); /* Make sure the border is taken into account. */
 	min-height: 297mm;
 	height: fit-content;
+	margin: 0; /* Reset margins that may be present on editable. We add them in other places. */
 	padding: 20mm 12mm;
 	border: 1px var(--ck-color-base-border) solid;
 	background: hsl(0, 0%, 100%);