@ckeditor/ckeditor5-engine 38.2.0-alpha.1 → 39.0.1

package/src/view/observer/bubblingemittermixin.js

@@ -6,7 +6,7 @@
  * @module engine/view/observer/bubblingemittermixin
  */
 import { CKEditorError, EmitterMixin, EventInfo, toArray } from '@ckeditor/ckeditor5-utils';
-import BubblingEventInfo from './bubblingeventinfo.js';
+import BubblingEventInfo from './bubblingeventinfo';
 const contextsSymbol = Symbol('bubbling contexts');
 /**
  * Bubbling emitter mixin for the view document as described in the {@link ~BubblingEmitter} interface.

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

@@ -6,9 +6,9 @@
  * @module engine/view/observer/bubblingeventinfo
  */
 import { EventInfo } from '@ckeditor/ckeditor5-utils';
-import type Document from '../document.js';
-import type Node from '../node.js';
-import type Range from '../range.js';
+import type Document from '../document';
+import type Node from '../node';
+import type Range from '../range';
 /**
  * The event object passed to bubbling event callbacks. It is used to provide information about the event as well as a tool to
  * manipulate it.

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

@@ -5,9 +5,9 @@
 /**
  * @module engine/view/observer/clickobserver
  */
-import DomEventObserver from './domeventobserver.js';
-import type DomEventData from './domeventdata.js';
-import type { BubblingEvent } from './bubblingemittermixin.js';
+import DomEventObserver from './domeventobserver';
+import type DomEventData from './domeventdata';
+import type { BubblingEvent } from './bubblingemittermixin';
 /**
  * {@link module:engine/view/document~Document#event:click Click} event observer.
  *

package/src/view/observer/clickobserver.js

@@ -5,7 +5,7 @@
 /**
  * @module engine/view/observer/clickobserver
  */
-import DomEventObserver from './domeventobserver.js';
+import DomEventObserver from './domeventobserver';
 /**
  * {@link module:engine/view/document~Document#event:click Click} event observer.
  *

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

@@ -5,9 +5,9 @@
 /**
  * @module engine/view/observer/compositionobserver
  */
-import DomEventObserver from './domeventobserver.js';
-import type View from '../view.js';
-import type DomEventData from './domeventdata.js';
+import DomEventObserver from './domeventobserver';
+import type View from '../view';
+import type DomEventData from './domeventdata';
 /**
  * {@link module:engine/view/document~Document#event:compositionstart Compositionstart},
  * {@link module:engine/view/document~Document#event:compositionupdate compositionupdate} and

package/src/view/observer/compositionobserver.js

@@ -5,7 +5,7 @@
 /**
  * @module engine/view/observer/compositionobserver
  */
-import DomEventObserver from './domeventobserver.js';
+import DomEventObserver from './domeventobserver';
 /**
  * {@link module:engine/view/document~Document#event:compositionstart Compositionstart},
  * {@link module:engine/view/document~Document#event:compositionupdate compositionupdate} and

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

@@ -2,9 +2,9 @@
  * @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
  */
-import type Document from '../document.js';
-import type Element from '../element.js';
-import type View from '../view.js';
+import type Document from '../document';
+import type Element from '../element';
+import type View from '../view';
 /**
  * Information about a DOM event in context of the {@link module:engine/view/document~Document}.
  * It wraps the native event, which usually should not be used as the wrapper contains

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

@@ -5,7 +5,7 @@
 /**
  * @module engine/view/observer/domeventobserver
  */
-import Observer from './observer.js';
+import Observer from './observer';
 import type { EventInfo } from '@ckeditor/ckeditor5-utils';
 /**
  * Base class for DOM event observers. This class handles

package/src/view/observer/domeventobserver.js

@@ -5,8 +5,8 @@
 /**
  * @module engine/view/observer/domeventobserver
  */
-import Observer from './observer.js';
-import DomEventData from './domeventdata.js';
+import Observer from './observer';
+import DomEventData from './domeventdata';
 /**
  * Base class for DOM event observers. This class handles
  * {@link module:engine/view/observer/observer~Observer#observe adding} listeners to DOM elements,

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

@@ -5,8 +5,8 @@
 /**
  * @module engine/view/observer/fakeselectionobserver
  */
-import Observer from './observer.js';
-import type View from '../view.js';
+import Observer from './observer';
+import type View from '../view';
 /**
  * Fake selection observer class. If view selection is fake it is placed in dummy DOM container. This observer listens
  * on {@link module:engine/view/document~Document#event:keydown keydown} events and handles moving fake view selection to the correct place

package/src/view/observer/fakeselectionobserver.js

@@ -5,8 +5,8 @@
 /**
  * @module engine/view/observer/fakeselectionobserver
  */
-import Observer from './observer.js';
-import ViewSelection from '../selection.js';
+import Observer from './observer';
+import ViewSelection from '../selection';
 import { keyCodes } from '@ckeditor/ckeditor5-utils';
 import { debounce } from 'lodash-es';
 /**

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

@@ -5,9 +5,9 @@
 /**
  * @module engine/view/observer/focusobserver
  */
-import DomEventObserver from './domeventobserver.js';
-import type DomEventData from './domeventdata.js';
-import type View from '../view.js';
+import DomEventObserver from './domeventobserver';
+import type DomEventData from './domeventdata';
+import type View from '../view';
 /**
  * {@link module:engine/view/document~Document#event:focus Focus}
  * and {@link module:engine/view/document~Document#event:blur blur} events observer.

package/src/view/observer/focusobserver.js

@@ -6,7 +6,7 @@
  * @module engine/view/observer/focusobserver
  */
 /* globals setTimeout, clearTimeout */
-import DomEventObserver from './domeventobserver.js';
+import DomEventObserver from './domeventobserver';
 /**
  * {@link module:engine/view/document~Document#event:focus Focus}
  * and {@link module:engine/view/document~Document#event:blur blur} events observer.

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

@@ -5,10 +5,10 @@
 /**
  * @module engine/view/observer/inputobserver
  */
-import DomEventObserver from './domeventobserver.js';
-import type DomEventData from './domeventdata.js';
-import type ViewRange from '../range.js';
-import DataTransfer from '../datatransfer.js';
+import DomEventObserver from './domeventobserver';
+import type DomEventData from './domeventdata';
+import type ViewRange from '../range';
+import DataTransfer from '../datatransfer';
 /**
  * Observer for events connected with data input.
  *

package/src/view/observer/inputobserver.js

@@ -5,8 +5,8 @@
 /**
  * @module engine/view/observer/inputobserver
  */
-import DomEventObserver from './domeventobserver.js';
-import DataTransfer from '../datatransfer.js';
+import DomEventObserver from './domeventobserver';
+import DataTransfer from '../datatransfer';
 import { env } from '@ckeditor/ckeditor5-utils';
 /**
  * Observer for events connected with data input.

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

@@ -5,8 +5,8 @@
 /**
  * @module engine/view/observer/keyobserver
  */
-import DomEventObserver from './domeventobserver.js';
-import type DomEventData from './domeventdata.js';
+import DomEventObserver from './domeventobserver';
+import type DomEventData from './domeventdata';
 import { type KeystrokeInfo } from '@ckeditor/ckeditor5-utils';
 /**
  * Observer for events connected with pressing keyboard keys.

package/src/view/observer/keyobserver.js

@@ -5,7 +5,7 @@
 /**
  * @module engine/view/observer/keyobserver
  */
-import DomEventObserver from './domeventobserver.js';
+import DomEventObserver from './domeventobserver';
 import { getCode } from '@ckeditor/ckeditor5-utils';
 /**
  * Observer for events connected with pressing keyboard keys.

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

@@ -5,8 +5,8 @@
 /**
  * @module engine/view/observer/mouseobserver
  */
-import DomEventObserver from './domeventobserver.js';
-import type DomEventData from './domeventdata.js';
+import DomEventObserver from './domeventobserver';
+import type DomEventData from './domeventdata';
 /**
  * Mouse events observer.
  *

package/src/view/observer/mouseobserver.js

@@ -5,7 +5,7 @@
 /**
  * @module engine/view/observer/mouseobserver
  */
-import DomEventObserver from './domeventobserver.js';
+import DomEventObserver from './domeventobserver';
 /**
  * Mouse events observer.
  *

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

@@ -5,10 +5,10 @@
 /**
  * @module engine/view/observer/mutationobserver
  */
-import Observer from './observer.js';
-import type DomConverter from '../domconverter.js';
-import type Renderer from '../renderer.js';
-import type View from '../view.js';
+import Observer from './observer';
+import type DomConverter from '../domconverter';
+import type Renderer from '../renderer';
+import type View from '../view';
 /**
  * Mutation observer's role is to watch for any DOM changes inside the editor that weren't
  * done by the editor's {@link module:engine/view/renderer~Renderer} itself and reverting these changes.

package/src/view/observer/mutationobserver.js

@@ -6,8 +6,8 @@
  * @module engine/view/observer/mutationobserver
  */
 /* globals window */
-import Observer from './observer.js';
-import { startsWithFiller } from '../filler.js';
+import Observer from './observer';
+import { startsWithFiller } from '../filler';
 import { isEqualWith } from 'lodash-es';
 /**
  * Mutation observer's role is to watch for any DOM changes inside the editor that weren't

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

@@ -2,8 +2,8 @@
  * @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
  */
-import type Document from '../document.js';
-import type View from '../view.js';
+import type Document from '../document';
+import type View from '../view';
 declare const Observer_base: {
     new (): import("@ckeditor/ckeditor5-utils").DomEmitter;
     prototype: import("@ckeditor/ckeditor5-utils").DomEmitter;

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

@@ -5,13 +5,13 @@
 /**
  * @module engine/view/observer/selectionobserver
  */
-import Observer from './observer.js';
-import MutationObserver from './mutationobserver.js';
-import type View from '../view.js';
-import type DocumentSelection from '../documentselection.js';
-import type DomConverter from '../domconverter.js';
-import type Selection from '../selection.js';
-import FocusObserver from './focusobserver.js';
+import Observer from './observer';
+import MutationObserver from './mutationobserver';
+import type View from '../view';
+import type DocumentSelection from '../documentselection';
+import type DomConverter from '../domconverter';
+import type Selection from '../selection';
+import FocusObserver from './focusobserver';
 type DomSelection = globalThis.Selection;
 /**
  * Selection observer class observes selection changes in the document. If a selection changes on the document this

package/src/view/observer/selectionobserver.js

@@ -6,11 +6,11 @@
  * @module engine/view/observer/selectionobserver
  */
 /* global setInterval, clearInterval */
-import Observer from './observer.js';
-import MutationObserver from './mutationobserver.js';
+import Observer from './observer';
+import MutationObserver from './mutationobserver';
 import { env } from '@ckeditor/ckeditor5-utils';
 import { debounce } from 'lodash-es';
-import FocusObserver from './focusobserver.js';
+import FocusObserver from './focusobserver';
 /**
  * Selection observer class observes selection changes in the document. If a selection changes on the document this
  * observer checks if the DOM selection is different from the {@link module:engine/view/document~Document#selection view selection}.
@@ -151,6 +151,8 @@ export default class SelectionObserver extends Observer {
             return;
         }
         this.view.hasDomSelection = true;
+        // Mark the latest focus change as complete (we got new selection after the focus so the selection is in the focused element).
+        this.focusObserver.flush();
         if (this.selection.isEqual(newViewSelection) && this.domConverter.isDomSelectionCorrect(domSelection)) {
             return;
         }
@@ -165,8 +167,6 @@ export default class SelectionObserver extends Observer {
             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).
-        this.focusObserver.flush();
         if (this.selection.isSimilar(newViewSelection)) {
             // If selection was equal and we are at this point of algorithm, it means that it was incorrect.
             // Just re-render it, no need to fire any events, etc.

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

@@ -5,10 +5,10 @@
 /**
  * @module engine/view/observer/tabobserver
  */
-import type View from '../view.js';
-import Observer from './observer.js';
-import type { KeyEventData } from './keyobserver.js';
-import type { BubblingEvent } from './bubblingemittermixin.js';
+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.
  *

package/src/view/observer/tabobserver.js

@@ -2,8 +2,8 @@
  * @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
  */
-import Observer from './observer.js';
-import BubblingEventInfo from './bubblingeventinfo.js';
+import Observer from './observer';
+import BubblingEventInfo from './bubblingeventinfo';
 import { keyCodes } from '@ckeditor/ckeditor5-utils';
 /**
  * Tab observer introduces the {@link module:engine/view/document~Document#event:tab `Document#tab`} event.

package/src/view/placeholder.d.ts

@@ -6,32 +6,34 @@
  * @module engine/view/placeholder
  */
 import '../../theme/placeholder.css';
-import type DowncastWriter from './downcastwriter.js';
-import type Element from './element.js';
-import type View from './view.js';
+import type DowncastWriter from './downcastwriter';
+import type EditableElement from './editableelement';
+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 change the placeholder text, change value of the `placeholder` property in the provided `element`.
  *
  * 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.text Placeholder text. It's **deprecated** and will be removed soon. Use
+ * {@link module:engine/view/placeholder~PlaceholderableElement#placeholder `options.element.placeholder`} instead.
  * @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;
+    element: PlaceholderableElement | EditableElement;
     isDirectHost?: boolean;
+    text?: string;
     keepOnFocus?: boolean;
 }): void;
 /**
@@ -83,3 +85,12 @@ export declare function hidePlaceholder(writer: DowncastWriter, element: Element
  * @param keepOnFocus Focusing the element will keep the placeholder visible.
  */
 export declare function needsPlaceholder(element: Element, keepOnFocus: boolean): boolean;
+/**
+ * Element that could have a placeholder.
+ */
+export interface PlaceholderableElement extends Element {
+    /**
+     * The text of element's placeholder.
+     */
+    placeholder?: string;
+}

package/src/view/placeholder.js

@@ -6,24 +6,27 @@
  * @module engine/view/placeholder
  */
 import '../../theme/placeholder.css';
+import { logWarning } from '@ckeditor/ckeditor5-utils';
 // Each document stores information about its placeholder elements and check functions.
 const documentPlaceholders = new WeakMap();
+let hasDisplayedPlaceholderDeprecationWarning = false;
 /**
  * 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 change the placeholder text, change value of the `placeholder` property in the provided `element`.
  *
  * 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.text Placeholder text. It's **deprecated** and will be removed soon. Use
+ * {@link module:engine/view/placeholder~PlaceholderableElement#placeholder `options.element.placeholder`} instead.
  * @param options.keepOnFocus If set `true`, the placeholder stay visible when the host element is focused.
  */
 export function enablePlaceholder({ view, element, text, isDirectHost = true, keepOnFocus = false }) {
@@ -39,15 +42,31 @@ export function enablePlaceholder({ view, element, text, isDirectHost = true, ke
             view.change(writer => updateDocumentPlaceholders(doc, writer));
         }, { priority: 'high' });
     }
-    // Store information about the element placeholder under its document.
-    documentPlaceholders.get(doc).set(element, {
-        text,
-        isDirectHost,
-        keepOnFocus,
-        hostElement: isDirectHost ? element : null
-    });
-    // Update the placeholders right away.
-    view.change(writer => updateDocumentPlaceholders(doc, writer));
+    if (element.is('editableElement')) {
+        element.on('change:placeholder', (evtInfo, evt, text) => {
+            setPlaceholder(text);
+        });
+    }
+    if (element.placeholder) {
+        setPlaceholder(element.placeholder);
+    }
+    else if (text) {
+        setPlaceholder(text);
+    }
+    if (text) {
+        showPlaceholderTextDeprecationWarning();
+    }
+    function setPlaceholder(text) {
+        // Store information about the element placeholder under its document.
+        documentPlaceholders.get(doc).set(element, {
+            text,
+            isDirectHost,
+            keepOnFocus,
+            hostElement: isDirectHost ? element : null
+        });
+        // Update the placeholders right away.
+        view.change(writer => updateDocumentPlaceholders(doc, writer));
+    }
 }
 /**
  * Disables the placeholder functionality from a given element.
@@ -228,3 +247,21 @@ function getChildPlaceholderHostSubstitute(parent) {
     }
     return null;
 }
+/**
+ * Displays a deprecation warning message in the console, but only once per page load.
+ */
+function showPlaceholderTextDeprecationWarning() {
+    if (!hasDisplayedPlaceholderDeprecationWarning) {
+        /**
+         * The "text" option in the {@link module:engine/view/placeholder~enablePlaceholder `enablePlaceholder()`}
+         * function is deprecated and will be removed soon.
+         *
+         * See the {@glink updating/guides/update-to-39#view-element-placeholder Migration to v39} guide for
+         * more information on how to apply this change.
+         *
+         * @error enableplaceholder-deprecated-text-option
+         */
+        logWarning('enableplaceholder-deprecated-text-option');
+    }
+    hasDisplayedPlaceholderDeprecationWarning = true;
+}

package/src/view/position.d.ts

@@ -5,13 +5,13 @@
 /**
  * @module engine/view/position
  */
-import TypeCheckable from './typecheckable.js';
-import EditableElement from './editableelement.js';
-import '@ckeditor/ckeditor5-utils/src/version.js';
-import type DocumentFragment from './documentfragment.js';
-import type Item from './item.js';
-import type Node from './node.js';
-import { default as TreeWalker, type TreeWalkerValue, type TreeWalkerOptions } from './treewalker.js';
+import TypeCheckable from './typecheckable';
+import EditableElement from './editableelement';
+import '@ckeditor/ckeditor5-utils/src/version';
+import type DocumentFragment from './documentfragment';
+import type Item from './item';
+import type Node from './node';
+import { default as TreeWalker, type TreeWalkerValue, type TreeWalkerOptions } from './treewalker';
 /**
  * Position in the view tree. Position is represented by its parent node and an offset in this parent.
  *

package/src/view/position.js

@@ -5,12 +5,12 @@
 /**
  * @module engine/view/position
  */
-import TypeCheckable from './typecheckable.js';
+import TypeCheckable from './typecheckable';
 import { CKEditorError, compareArrays } from '@ckeditor/ckeditor5-utils';
-import EditableElement from './editableelement.js';
+import EditableElement from './editableelement';
 // To check if component is loaded more than once.
-import '@ckeditor/ckeditor5-utils/src/version.js';
-import { default as TreeWalker } from './treewalker.js';
+import '@ckeditor/ckeditor5-utils/src/version';
+import { default as TreeWalker } from './treewalker';
 /**
  * Position in the view tree. Position is represented by its parent node and an offset in this parent.
  *

package/src/view/range.d.ts

@@ -5,13 +5,13 @@
 /**
  * @module engine/view/range
  */
-import TypeCheckable from './typecheckable.js';
-import Position from './position.js';
-import type DocumentFragment from './documentfragment.js';
-import type Element from './element.js';
-import type Item from './item.js';
-import type Node from './node.js';
-import { default as TreeWalker, type TreeWalkerValue, type TreeWalkerOptions } from './treewalker.js';
+import TypeCheckable from './typecheckable';
+import Position from './position';
+import type DocumentFragment from './documentfragment';
+import type Element from './element';
+import type Item from './item';
+import type Node from './node';
+import { default as TreeWalker, type TreeWalkerValue, type TreeWalkerOptions } from './treewalker';
 /**
  * Range in the view tree. A range is represented by its start and end {@link module:engine/view/position~Position positions}.
  *

package/src/view/range.js

@@ -5,9 +5,9 @@
 /**
  * @module engine/view/range
  */
-import TypeCheckable from './typecheckable.js';
-import Position from './position.js';
-import { default as TreeWalker } from './treewalker.js';
+import TypeCheckable from './typecheckable';
+import Position from './position';
+import { default as TreeWalker } from './treewalker';
 /**
  * Range in the view tree. A range is represented by its start and end {@link module:engine/view/position~Position positions}.
  *

package/src/view/rawelement.d.ts

@@ -5,11 +5,11 @@
 /**
  * @module engine/view/rawelement
  */
-import Element, { type ElementAttributes } from './element.js';
-import Node from './node.js';
-import type Document from './document.js';
-import type DomConverter from './domconverter.js';
-import type Item from './item.js';
+import Element, { type ElementAttributes } from './element';
+import Node from './node';
+import type Document from './document';
+import type DomConverter from './domconverter';
+import type Item from './item';
 type DomElement = globalThis.HTMLElement;
 /**
  * The raw element class.

package/src/view/rawelement.js

@@ -6,8 +6,8 @@
 /**
  * @module engine/view/rawelement
  */
-import Element from './element.js';
-import Node from './node.js';
+import Element from './element';
+import Node from './node';
 import { CKEditorError } from '@ckeditor/ckeditor5-utils';
 /**
  * The raw element class.

package/src/view/renderer.d.ts

@@ -2,11 +2,11 @@
  * @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
  */
-import type { ChangeType } from './document.js';
-import type DocumentSelection from './documentselection.js';
-import type DomConverter from './domconverter.js';
-import type ViewElement from './element.js';
-import type ViewNode from './node.js';
+import type { ChangeType } from './document';
+import type DocumentSelection from './documentselection';
+import type DomConverter from './domconverter';
+import type ViewElement from './element';
+import type ViewNode from './node';
 import '../../theme/renderer.css';
 type DomDocument = globalThis.Document;
 declare const Renderer_base: {