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

package/src/view/observer/selectionobserver.js

@@ -20,91 +20,20 @@ import FocusObserver from './focusobserver';
  * This observer also manages the {@link module:engine/view/document~Document#isSelecting} property of the view document.
  *
  * Note that this observer is attached by the {@link module:engine/view/view~View} and is available by default.
- *
- * @extends module:engine/view/observer/observer~Observer
  */
 export default class SelectionObserver extends Observer {
     constructor(view) {
         super(view);
-        /**
-         * Instance of the mutation observer. Selection observer calls
-         * {@link module:engine/view/observer/mutationobserver~MutationObserver#flush} to ensure that the mutations will be handled
-         * before the {@link module:engine/view/document~Document#event:selectionChange} event is fired.
-         *
-         * @readonly
-         * @member {module:engine/view/observer/mutationobserver~MutationObserver}
-         * module:engine/view/observer/selectionobserver~SelectionObserver#mutationObserver
-         */
         this.mutationObserver = view.getObserver(MutationObserver);
-        /**
-         * Instance of the focus observer. Selection observer calls
-         * {@link module:engine/view/observer/focusobserver~FocusObserver#flush} to mark the latest focus change as complete.
-         *
-         * @readonly
-         * @member {module:engine/view/observer/focusobserver~FocusObserver}
-         * module:engine/view/observer/focusobserver~FocusObserver#focusObserver
-         */
         this.focusObserver = view.getObserver(FocusObserver);
-        /**
-         * Reference to the view {@link module:engine/view/documentselection~DocumentSelection} object used to compare
-         * new selection with it.
-         *
-         * @readonly
-         * @member {module:engine/view/documentselection~DocumentSelection}
-         * module:engine/view/observer/selectionobserver~SelectionObserver#selection
-         */
         this.selection = this.document.selection;
-        /* eslint-disable max-len */
-        /**
-         * Reference to the {@link module:engine/view/view~View#domConverter}.
-         *
-         * @readonly
-         * @member {module:engine/view/domconverter~DomConverter} module:engine/view/observer/selectionobserver~SelectionObserver#domConverter
-         */
-        /* eslint-enable max-len */
         this.domConverter = view.domConverter;
-        /**
-         * A set of documents which have added `selectionchange` listener to avoid adding a listener twice to the same
-         * document.
-         *
-         * @private
-         * @member {WeakSet.<Document>} module:engine/view/observer/selectionobserver~SelectionObserver#_documents
-         */
         this._documents = new WeakSet();
-        /**
-         * Fires debounced event `selectionChangeDone`. It uses `lodash#debounce` method to delay function call.
-         *
-         * @private
-         * @param {Object} data Selection change data.
-         * @method #_fireSelectionChangeDoneDebounced
-         */
         this._fireSelectionChangeDoneDebounced = debounce(data => {
             this.document.fire('selectionChangeDone', data);
         }, 200);
-        /**
-         * When called, starts clearing the {@link #_loopbackCounter} counter in time intervals. When the number of selection
-         * changes exceeds a certain limit within the interval of time, the observer will not fire `selectionChange` but warn about
-         * possible infinite selection loop.
-         *
-         * @private
-         * @member {Number} #_clearInfiniteLoopInterval
-         */
         this._clearInfiniteLoopInterval = setInterval(() => this._clearInfiniteLoop(), 1000);
-        /**
-         * Unlocks the `isSelecting` state of the view document in case the selection observer did not record this fact
-         * correctly (for whatever reason). It is a safeguard (paranoid check), that returns document to the normal state
-         * after a certain period of time (debounced, postponed by each selectionchange event).
-         *
-         * @private
-         * @method #_documentIsSelectingInactivityTimeoutDebounced
-         */
         this._documentIsSelectingInactivityTimeoutDebounced = debounce(() => (this.document.isSelecting = false), 5000);
-        /**
-         * Private property to check if the code does not enter infinite loop.
-         *
-         * @private
-         * @member {Number} module:engine/view/observer/selectionobserver~SelectionObserver#_loopbackCounter
-         */
         this._loopbackCounter = 0;
     }
     /**
@@ -142,19 +71,19 @@ export default class SelectionObserver extends Observer {
         // handler would like to check it and update (for example table multi cell selection).
         this.listenTo(domDocument, 'mouseup', endDocumentIsSelecting, { priority: 'highest', useCapture: true });
         this.listenTo(domDocument, 'selectionchange', (evt, domEvent) => {
-            // @if CK_DEBUG_TYPING // if ( window.logCKETyping ) {
-            // @if CK_DEBUG_TYPING // 	const domSelection = domDocument.defaultView.getSelection();
+            // @if CK_DEBUG_TYPING // if ( ( window as any ).logCKETyping ) {
+            // @if CK_DEBUG_TYPING // 	const domSelection = domDocument.defaultView!.getSelection();
             // @if CK_DEBUG_TYPING // 	console.group( '%c[SelectionObserver]%c selectionchange', 'color:green', ''
             // @if CK_DEBUG_TYPING // 	);
             // @if CK_DEBUG_TYPING // 	console.info( '%c[SelectionObserver]%c DOM Selection:', 'font-weight:bold;color:green', '',
-            // @if CK_DEBUG_TYPING // 		{ node: domSelection.anchorNode, offset: domSelection.anchorOffset },
-            // @if CK_DEBUG_TYPING // 		{ node: domSelection.focusNode, offset: domSelection.focusOffset }
+            // @if CK_DEBUG_TYPING // 		{ node: domSelection!.anchorNode, offset: domSelection!.anchorOffset },
+            // @if CK_DEBUG_TYPING // 		{ node: domSelection!.focusNode, offset: domSelection!.focusOffset }
             // @if CK_DEBUG_TYPING // 	);
             // @if CK_DEBUG_TYPING // }
             // The Renderer is disabled while composing on non-android browsers, so we can't update the view selection
             // because the DOM and view tree drifted apart. Position mapping could fail because of it.
             if (this.document.isComposing && !env.isAndroid) {
-                // @if CK_DEBUG_TYPING // if ( window.logCKETyping ) {
+                // @if CK_DEBUG_TYPING // if ( ( window as any ).logCKETyping ) {
                 // @if CK_DEBUG_TYPING // 	console.info( '%c[SelectionObserver]%c Selection change ignored (isComposing)',
                 // @if CK_DEBUG_TYPING // 		'font-weight:bold;color:green', ''
                 // @if CK_DEBUG_TYPING // 	);
@@ -163,7 +92,7 @@ export default class SelectionObserver extends Observer {
                 return;
             }
             this._handleSelectionChange(domEvent, domDocument);
-            // @if CK_DEBUG_TYPING // if ( window.logCKETyping ) {
+            // @if CK_DEBUG_TYPING // if ( ( window as any ).logCKETyping ) {
             // @if CK_DEBUG_TYPING // 	console.groupEnd();
             // @if CK_DEBUG_TYPING // }
             // Defer the safety timeout when the selection changes (e.g. the user keeps extending the selection
@@ -181,20 +110,20 @@ export default class SelectionObserver extends Observer {
         this._fireSelectionChangeDoneDebounced.cancel();
         this._documentIsSelectingInactivityTimeoutDebounced.cancel();
     }
-    // @if CK_DEBUG //	_reportInfiniteLoop() {
-    // @if CK_DEBUG //		throw new Error(
-    // @if CK_DEBUG //			'Selection change observer detected an infinite rendering loop.\n\n' +
-    // @if CK_DEBUG //	 		'⚠️⚠️ Report this error on https://github.com/ckeditor/ckeditor5/issues/11658.'
-    // @if CK_DEBUG //		);
-    // @if CK_DEBUG //	}
+    /* istanbul ignore next */
+    _reportInfiniteLoop() {
+        // @if CK_DEBUG //		throw new Error(
+        // @if CK_DEBUG //			'Selection change observer detected an infinite rendering loop.\n\n' +
+        // @if CK_DEBUG //	 		'⚠️⚠️ Report this error on https://github.com/ckeditor/ckeditor5/issues/11658.'
+        // @if CK_DEBUG //		);
+    }
     /**
      * Selection change listener. {@link module:engine/view/observer/mutationobserver~MutationObserver#flush Flush} mutations, check if
      * a selection changes and fires {@link module:engine/view/document~Document#event:selectionChange} event on every change
      * and {@link module:engine/view/document~Document#event:selectionChangeDone} when a selection stop changing.
      *
-     * @private
-     * @param {Event} domEvent DOM event.
-     * @param {Document} domDocument DOM document.
+     * @param domEvent DOM event.
+     * @param domDocument DOM document.
      */
     _handleSelectionChange(domEvent, domDocument) {
         if (!this.isEnabled) {
@@ -227,8 +156,7 @@ export default class SelectionObserver extends Observer {
             // Most probably you try to put the selection in the position which is not allowed
             // by the browser and browser fixes it automatically what causes `selectionchange` event on
             // which a loopback through a model tries to re-render the wrong selection and again.
-            //
-            // @if CK_DEBUG // this._reportInfiniteLoop();
+            this._reportInfiniteLoop();
             return;
         }
         // Mark the latest focus change as complete (we got new selection after the focus so the selection is in the focused element).
@@ -244,7 +172,7 @@ export default class SelectionObserver extends Observer {
                 newSelection: newViewSelection,
                 domSelection
             };
-            // @if CK_DEBUG_TYPING // if ( window.logCKETyping ) {
+            // @if CK_DEBUG_TYPING // if ( ( window as any ).logCKETyping ) {
             // @if CK_DEBUG_TYPING // 	console.info( '%c[SelectionObserver]%c Fire selection change:',
             // @if CK_DEBUG_TYPING // 		'font-weight:bold;color:green', '',
             // @if CK_DEBUG_TYPING // 		newViewSelection.getFirstRange()
@@ -261,26 +189,8 @@ export default class SelectionObserver extends Observer {
     }
     /**
      * Clears `SelectionObserver` internal properties connected with preventing infinite loop.
-     *
-     * @protected
      */
     _clearInfiniteLoop() {
         this._loopbackCounter = 0;
     }
 }
-/**
- * Fired when selection stops changing.
- *
- * Introduced by {@link module:engine/view/observer/selectionobserver~SelectionObserver}.
- *
- * Note that because {@link module:engine/view/observer/selectionobserver~SelectionObserver} is attached by the
- * {@link module:engine/view/view~View} this event is available by default.
- *
- * @see module:engine/view/observer/selectionobserver~SelectionObserver
- * @event module:engine/view/document~Document#event:selectionChangeDone
- * @param {Object} data
- * @param {module:engine/view/documentselection~DocumentSelection} data.oldSelection Old View selection which is
- * {@link module:engine/view/document~Document#selection}.
- * @param {module:engine/view/selection~Selection} data.newSelection New View selection which is converted DOM selection.
- * @param {Selection} data.domSelection Native DOM selection.
- */

package/src/view/observer/tabobserver.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module engine/view/observer/tabobserver
+ */
+import type View from '../view';
+import Observer from './observer';
+import type { KeyEventData } from './keyobserver';
+import type { BubblingEvent } from './bubblingemittermixin';
+/**
+ * Tab observer introduces the {@link module:engine/view/document~Document#event:tab `Document#tab`} event.
+ *
+ * Note that because {@link module:engine/view/observer/tabobserver~TabObserver} is attached by the
+ * {@link module:engine/view/view~View}, this event is available by default.
+ */
+export default class TabObserver extends Observer {
+    /**
+     * @inheritDoc
+     */
+    constructor(view: View);
+    /**
+     * @inheritDoc
+     */
+    observe(): void;
+}
+/**
+ * Event fired when the user presses a tab key.
+ *
+ * Introduced by {@link module:engine/view/observer/tabobserver~TabObserver}.
+ *
+ * Note that because {@link module:engine/view/observer/tabobserver~TabObserver} is attached by the
+ * {@link module:engine/view/view~View}, this event is available by default.
+ *
+ * @eventName module:engine/view/document~Document#tab
+ * @param data
+ */
+export type ViewDocumentTabEvent = BubblingEvent<{
+    name: 'tab';
+    args: [data: KeyEventData];
+}>;

package/src/view/observer/tabobserver.js

@@ -10,8 +10,6 @@ import { keyCodes } from '@ckeditor/ckeditor5-utils';
  *
  * Note that because {@link module:engine/view/observer/tabobserver~TabObserver} is attached by the
  * {@link module:engine/view/view~View}, this event is available by default.
- *
- * @extends module:engine/view/observer/observer~Observer
  */
 export default class TabObserver extends Observer {
     /**
@@ -38,15 +36,3 @@ export default class TabObserver extends Observer {
      */
     observe() { }
 }
-/**
- * Event fired when the user presses a tab key.
- *
- * Introduced by {@link module:engine/view/observer/tabobserver~TabObserver}.
- *
- * Note that because {@link module:engine/view/observer/tabobserver~TabObserver} is attached by the
- * {@link module:engine/view/view~View}, this event is available by default.
- *
- * @event module:engine/view/document~Document#event:tab
- *
- * @param {module:engine/view/observer/domeventdata~DomEventData} data
- */

package/src/view/placeholder.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module engine/view/placeholder
+ */
+import '../../theme/placeholder.css';
+import type DowncastWriter from './downcastwriter';
+import type Element from './element';
+import type View from './view';
+/**
+ * A helper that enables a placeholder on the provided view element (also updates its visibility).
+ * The placeholder is a CSS pseudo–element (with a text content) attached to the element.
+ *
+ * To change the placeholder text, simply call this method again with new options.
+ *
+ * To disable the placeholder, use {@link module:engine/view/placeholder~disablePlaceholder `disablePlaceholder()`} helper.
+ *
+ * @param options Configuration options of the placeholder.
+ * @param options.view Editing view instance.
+ * @param options.element Element that will gain a placeholder. See `options.isDirectHost` to learn more.
+ * @param options.text Placeholder text.
+ * @param options.isDirectHost If set `false`, the placeholder will not be enabled directly
+ * in the passed `element` but in one of its children (selected automatically, i.e. a first empty child element).
+ * Useful when attaching placeholders to elements that can host other elements (not just text), for instance,
+ * editable root elements.
+ * @param options.keepOnFocus If set `true`, the placeholder stay visible when the host element is focused.
+ */
+export declare function enablePlaceholder({ view, element, text, isDirectHost, keepOnFocus }: {
+    view: View;
+    element: Element;
+    text: string;
+    isDirectHost?: boolean;
+    keepOnFocus?: boolean;
+}): void;
+/**
+ * Disables the placeholder functionality from a given element.
+ *
+ * See {@link module:engine/view/placeholder~enablePlaceholder `enablePlaceholder()`} to learn more.
+ */
+export declare function disablePlaceholder(view: View, element: Element): void;
+/**
+ * Shows a placeholder in the provided element by changing related attributes and CSS classes.
+ *
+ * **Note**: This helper will not update the placeholder visibility nor manage the
+ * it in any way in the future. What it does is a one–time state change of an element. Use
+ * {@link module:engine/view/placeholder~enablePlaceholder `enablePlaceholder()`} and
+ * {@link module:engine/view/placeholder~disablePlaceholder `disablePlaceholder()`} for full
+ * placeholder functionality.
+ *
+ * **Note**: This helper will blindly show the placeholder directly in the root editable element if
+ * one is passed, which could result in a visual clash if the editable element has some children
+ * (for instance, an empty paragraph). Use {@link module:engine/view/placeholder~enablePlaceholder `enablePlaceholder()`}
+ * in that case or make sure the correct element is passed to the helper.
+ *
+ * @returns `true`, if any changes were made to the `element`.
+ */
+export declare function showPlaceholder(writer: DowncastWriter, element: Element): boolean;
+/**
+ * Hides a placeholder in the element by changing related attributes and CSS classes.
+ *
+ * **Note**: This helper will not update the placeholder visibility nor manage the
+ * it in any way in the future. What it does is a one–time state change of an element. Use
+ * {@link module:engine/view/placeholder~enablePlaceholder `enablePlaceholder()`} and
+ * {@link module:engine/view/placeholder~disablePlaceholder `disablePlaceholder()`} for full
+ * placeholder functionality.
+ *
+ * @returns `true`, if any changes were made to the `element`.
+ */
+export declare function hidePlaceholder(writer: DowncastWriter, element: Element): boolean;
+/**
+ * Checks if a placeholder should be displayed in the element.
+ *
+ * **Note**: This helper will blindly check the possibility of showing a placeholder directly in the
+ * root editable element if one is passed, which may not be the expected result. If an element can
+ * host other elements (not just text), most likely one of its children should be checked instead
+ * because it will be the final host for the placeholder. Use
+ * {@link module:engine/view/placeholder~enablePlaceholder `enablePlaceholder()`} in that case or make
+ * sure the correct element is passed to the helper.
+ *
+ * @param element Element that holds the placeholder.
+ * @param keepOnFocus Focusing the element will keep the placeholder visible.
+ */
+export declare function needsPlaceholder(element: Element, keepOnFocus: boolean): boolean;

package/src/view/placeholder.js

@@ -16,19 +16,17 @@ const documentPlaceholders = new WeakMap();
  *
  * To disable the placeholder, use {@link module:engine/view/placeholder~disablePlaceholder `disablePlaceholder()`} helper.
  *
- * @param {Object} [options] Configuration options of the placeholder.
- * @param {module:engine/view/view~View} options.view Editing view instance.
- * @param {module:engine/view/element~Element} options.element Element that will gain a placeholder.
- * See `options.isDirectHost` to learn more.
- * @param {String} options.text Placeholder text.
- * @param {Boolean} [options.isDirectHost=true] If set `false`, the placeholder will not be enabled directly
+ * @param options Configuration options of the placeholder.
+ * @param options.view Editing view instance.
+ * @param options.element Element that will gain a placeholder. See `options.isDirectHost` to learn more.
+ * @param options.text Placeholder text.
+ * @param options.isDirectHost If set `false`, the placeholder will not be enabled directly
  * in the passed `element` but in one of its children (selected automatically, i.e. a first empty child element).
  * Useful when attaching placeholders to elements that can host other elements (not just text), for instance,
  * editable root elements.
- * @param {Boolean} [options.keepOnFocus=false] If set `true`, the placeholder stay visible when the host element is focused.
+ * @param options.keepOnFocus If set `true`, the placeholder stay visible when the host element is focused.
  */
-export function enablePlaceholder(options) {
-    const { view, element, text, isDirectHost = true, keepOnFocus = false } = options;
+export function enablePlaceholder({ view, element, text, isDirectHost = true, keepOnFocus = false }) {
     const doc = view.document;
     // Use a single a single post fixer per—document to update all placeholders.
     if (!documentPlaceholders.has(doc)) {
@@ -55,9 +53,6 @@ export function enablePlaceholder(options) {
  * Disables the placeholder functionality from a given element.
  *
  * See {@link module:engine/view/placeholder~enablePlaceholder `enablePlaceholder()`} to learn more.
- *
- * @param {module:engine/view/view~View} view
- * @param {module:engine/view/element~Element} element
  */
 export function disablePlaceholder(view, element) {
     const doc = element.document;
@@ -86,9 +81,7 @@ export function disablePlaceholder(view, element) {
  * (for instance, an empty paragraph). Use {@link module:engine/view/placeholder~enablePlaceholder `enablePlaceholder()`}
  * in that case or make sure the correct element is passed to the helper.
  *
- * @param {module:engine/view/downcastwriter~DowncastWriter} writer
- * @param {module:engine/view/element~Element} element
- * @returns {Boolean} `true`, if any changes were made to the `element`.
+ * @returns `true`, if any changes were made to the `element`.
  */
 export function showPlaceholder(writer, element) {
     if (!element.hasClass('ck-placeholder')) {
@@ -106,9 +99,7 @@ export function showPlaceholder(writer, element) {
  * {@link module:engine/view/placeholder~disablePlaceholder `disablePlaceholder()`} for full
  * placeholder functionality.
  *
- * @param {module:engine/view/downcastwriter~DowncastWriter} writer
- * @param {module:engine/view/element~Element} element
- * @returns {Boolean} `true`, if any changes were made to the `element`.
+ * @returns `true`, if any changes were made to the `element`.
  */
 export function hidePlaceholder(writer, element) {
     if (element.hasClass('ck-placeholder')) {
@@ -127,9 +118,8 @@ export function hidePlaceholder(writer, element) {
  * {@link module:engine/view/placeholder~enablePlaceholder `enablePlaceholder()`} in that case or make
  * sure the correct element is passed to the helper.
  *
- * @param {module:engine/view/element~Element} element Element that holds the placeholder.
- * @param {Boolean} keepOnFocus Focusing the element will keep the placeholder visible.
- * @returns {Boolean}
+ * @param element Element that holds the placeholder.
+ * @param keepOnFocus Focusing the element will keep the placeholder visible.
  */
 export function needsPlaceholder(element, keepOnFocus) {
     if (!element.isAttached()) {
@@ -158,12 +148,11 @@ export function needsPlaceholder(element, keepOnFocus) {
     // If document is focused and the element is empty but the selection is not anchored inside it.
     return !!selectionAnchor && selectionAnchor.parent !== element;
 }
-// Updates all placeholders associated with a document in a post–fixer callback.
-//
-// @private
-// @param { module:engine/view/document~Document} doc
-// @param {module:engine/view/downcastwriter~DowncastWriter} writer
-// @returns {Boolean} True if any changes were made to the view document.
+/**
+ * Updates all placeholders associated with a document in a post–fixer callback.
+ *
+ * @returns True if any changes were made to the view document.
+ */
 function updateDocumentPlaceholders(doc, writer) {
     const placeholders = documentPlaceholders.get(doc);
     const directHostElements = [];
@@ -200,15 +189,11 @@ function updateDocumentPlaceholders(doc, writer) {
     }
     return wasViewModified;
 }
-// Updates a single placeholder in a post–fixer callback.
-//
-// @private
-// @param {module:engine/view/downcastwriter~DowncastWriter} writer
-// @param {module:engine/view/element~Element} element
-// @param {Object} config Configuration of the placeholder
-// @param {String} config.text
-// @param {Boolean} config.isDirectHost
-// @returns {Boolean} True if any changes were made to the view document.
+/**
+ * Updates a single placeholder in a post–fixer callback.
+ *
+ * @returns True if any changes were made to the view document.
+ */
 function updatePlaceholder(writer, element, config) {
     const { text, isDirectHost, hostElement } = config;
     let wasViewModified = false;
@@ -229,13 +214,11 @@ function updatePlaceholder(writer, element, config) {
     }
     return wasViewModified;
 }
-// Gets a child element capable of displaying a placeholder if a parent element can host more
-// than just text (for instance, when it is a root editable element). The child element
-// can then be used in other placeholder helpers as a substitute of its parent.
-//
-// @private
-// @param {module:engine/view/element~Element} parent
-// @returns {module:engine/view/element~Element|null}
+/**
+ * Gets a child element capable of displaying a placeholder if a parent element can host more
+ * than just text (for instance, when it is a root editable element). The child element
+ * can then be used in other placeholder helpers as a substitute of its parent.
+ */
 function getChildPlaceholderHostSubstitute(parent) {
     if (parent.childCount) {
         const firstChild = parent.getChild(0);