@ckeditor/ckeditor5-engine 0.0.0-internal-20241017.0

package/src/view/observer/selectionobserver.js

@@ -0,0 +1,220 @@
+/**
+ * @license Copyright (c) 2003-2024, 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/selectionobserver
+ */
+/* global setInterval, clearInterval */
+import Observer from './observer.js';
+import MutationObserver from './mutationobserver.js';
+import FocusObserver from './focusobserver.js';
+import { env } from '@ckeditor/ckeditor5-utils';
+import { debounce } from 'lodash-es';
+/**
+ * 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}.
+ * The selection observer fires {@link module:engine/view/document~Document#event:selectionChange} event only if
+ * a selection change was the only change in the document and the DOM selection is different from the view selection.
+ *
+ * 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.
+ */
+export default class SelectionObserver extends Observer {
+    constructor(view) {
+        super(view);
+        this.mutationObserver = view.getObserver(MutationObserver);
+        this.focusObserver = view.getObserver(FocusObserver);
+        this.selection = this.document.selection;
+        this.domConverter = view.domConverter;
+        this._documents = new WeakSet();
+        this._fireSelectionChangeDoneDebounced = debounce(data => {
+            this.document.fire('selectionChangeDone', data);
+        }, 200);
+        this._clearInfiniteLoopInterval = setInterval(() => this._clearInfiniteLoop(), 1000);
+        this._documentIsSelectingInactivityTimeoutDebounced = debounce(() => (this.document.isSelecting = false), 5000);
+        this._loopbackCounter = 0;
+    }
+    /**
+     * @inheritDoc
+     */
+    observe(domElement) {
+        const domDocument = domElement.ownerDocument;
+        const startDocumentIsSelecting = () => {
+            this.document.isSelecting = true;
+            // Let's activate the safety timeout each time the document enters the "is selecting" state.
+            this._documentIsSelectingInactivityTimeoutDebounced();
+        };
+        const endDocumentIsSelecting = () => {
+            if (!this.document.isSelecting) {
+                return;
+            }
+            // Make sure that model selection is up-to-date at the end of selecting process.
+            // Sometimes `selectionchange` events could arrive after the `mouseup` event and that selection could be already outdated.
+            this._handleSelectionChange(domDocument);
+            this.document.isSelecting = false;
+            // The safety timeout can be canceled when the document leaves the "is selecting" state.
+            this._documentIsSelectingInactivityTimeoutDebounced.cancel();
+        };
+        // The document has the "is selecting" state while the user keeps making (extending) the selection
+        // (e.g. by holding the mouse button and moving the cursor). The state resets when they either released
+        // the mouse button or interrupted the process by pressing or releasing any key.
+        this.listenTo(domElement, 'selectstart', startDocumentIsSelecting, { priority: 'highest' });
+        this.listenTo(domElement, 'keydown', endDocumentIsSelecting, { priority: 'highest', useCapture: true });
+        this.listenTo(domElement, 'keyup', endDocumentIsSelecting, { priority: 'highest', useCapture: true });
+        // Add document-wide listeners only once. This method could be called for multiple editing roots.
+        if (this._documents.has(domDocument)) {
+            return;
+        }
+        // This listener is using capture mode to make sure that selection is upcasted before any other
+        // 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', () => {
+            // @if CK_DEBUG_TYPING // if ( ( window as any ).logCKETyping ) {
+            // @if CK_DEBUG_TYPING // 	_debouncedLine();
+            // @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 // 	);
+            // @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 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 // 	);
+                // @if CK_DEBUG_TYPING // 	console.groupEnd();
+                // @if CK_DEBUG_TYPING // }
+                return;
+            }
+            this._handleSelectionChange(domDocument);
+            // @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
+            // using their mouse).
+            this._documentIsSelectingInactivityTimeoutDebounced();
+        });
+        // Update the model DocumentSelection just after the Renderer and the SelectionObserver are locked.
+        // We do this synchronously (without waiting for the `selectionchange` DOM event) as browser updates
+        // the DOM selection (but not visually) to span the text that is under composition and could be replaced.
+        this.listenTo(this.view.document, 'compositionstart', () => {
+            // @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 update selection on compositionstart', '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 // 	);
+            // @if CK_DEBUG_TYPING // }
+            this._handleSelectionChange(domDocument);
+            // @if CK_DEBUG_TYPING // if ( ( window as any ).logCKETyping ) {
+            // @if CK_DEBUG_TYPING // 	console.groupEnd();
+            // @if CK_DEBUG_TYPING // }
+        }, { priority: 'lowest' });
+        this._documents.add(domDocument);
+    }
+    /**
+     * @inheritDoc
+     */
+    stopObserving(domElement) {
+        this.stopListening(domElement);
+    }
+    /**
+     * @inheritDoc
+     */
+    destroy() {
+        super.destroy();
+        clearInterval(this._clearInfiniteLoopInterval);
+        this._fireSelectionChangeDoneDebounced.cancel();
+        this._documentIsSelectingInactivityTimeoutDebounced.cancel();
+    }
+    /* istanbul ignore next -- @preserve */
+    _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.
+     *
+     * @param domDocument DOM document.
+     */
+    _handleSelectionChange(domDocument) {
+        if (!this.isEnabled) {
+            return;
+        }
+        const domSelection = domDocument.defaultView.getSelection();
+        if (this.checkShouldIgnoreEventFromTarget(domSelection.anchorNode)) {
+            return;
+        }
+        // Ensure the mutation event will be before selection event on all browsers.
+        this.mutationObserver.flush();
+        const newViewSelection = this.domConverter.domSelectionToView(domSelection);
+        // Do not convert selection change if the new view selection has no ranges in it.
+        //
+        // It means that the DOM selection is in some way incorrect. Ranges that were in the DOM selection could not be
+        // converted to the view. This happens when the DOM selection was moved outside of the editable element.
+        if (newViewSelection.rangeCount == 0) {
+            this.view.hasDomSelection = false;
+            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;
+        }
+        // Ensure we are not in the infinite loop (#400).
+        // This counter is reset each second. 60 selection changes in 1 second is enough high number
+        // to be very difficult (impossible) to achieve using just keyboard keys (during normal editor use).
+        if (++this._loopbackCounter > 60) {
+            // Selection change observer detected an infinite rendering loop.
+            // 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.
+            this._reportInfiniteLoop();
+            return;
+        }
+        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.
+            this.view.forceRender();
+        }
+        else {
+            const data = {
+                oldSelection: this.selection,
+                newSelection: newViewSelection,
+                domSelection
+            };
+            // @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()
+            // @if CK_DEBUG_TYPING // 	);
+            // @if CK_DEBUG_TYPING // }
+            // Prepare data for new selection and fire appropriate events.
+            this.document.fire('selectionChange', data);
+            // Call `#_fireSelectionChangeDoneDebounced` every time when `selectionChange` event is fired.
+            // This function is debounced what means that `selectionChangeDone` event will be fired only when
+            // defined int the function time will elapse since the last time the function was called.
+            // So `selectionChangeDone` will be fired when selection will stop changing.
+            this._fireSelectionChangeDoneDebounced(data);
+        }
+    }
+    /**
+     * Clears `SelectionObserver` internal properties connected with preventing infinite loop.
+     */
+    _clearInfiniteLoop() {
+        this._loopbackCounter = 0;
+    }
+}

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

@@ -0,0 +1,46 @@
+/**
+ * @license Copyright (c) 2003-2024, 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.js';
+import Observer from './observer.js';
+import type { KeyEventData } from './keyobserver.js';
+import type { BubblingEvent } from './bubblingemittermixin.js';
+/**
+ * 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;
+    /**
+     * @inheritDoc
+     */
+    stopObserving(): 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

@@ -0,0 +1,42 @@
+/**
+ * @license Copyright (c) 2003-2024, 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 { keyCodes } from '@ckeditor/ckeditor5-utils';
+/**
+ * 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) {
+        super(view);
+        const doc = this.document;
+        doc.on('keydown', (evt, data) => {
+            if (!this.isEnabled ||
+                data.keyCode != keyCodes.tab ||
+                data.ctrlKey) {
+                return;
+            }
+            const event = new BubblingEventInfo(doc, 'tab', doc.selection.getFirstRange());
+            doc.fire(event, data);
+            if (event.stop.called) {
+                evt.stop();
+            }
+        });
+    }
+    /**
+     * @inheritDoc
+     */
+    observe() { }
+    /**
+     * @inheritDoc
+     */
+    stopObserving() { }
+}

package/src/view/placeholder.d.ts

@@ -0,0 +1,96 @@
+/**
+ * @license Copyright (c) 2003-2024, 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.js';
+import type EditableElement from './editableelement.js';
+import type Element from './element.js';
+import type View from './view.js';
+/**
+ * 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, 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.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: PlaceholderableElement | EditableElement;
+    isDirectHost?: boolean;
+    text?: string;
+    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;
+/**
+ * Element that could have a placeholder.
+ */
+export interface PlaceholderableElement extends Element {
+    /**
+     * The text of element's placeholder.
+     */
+    placeholder?: string;
+}

package/src/view/placeholder.js

@@ -0,0 +1,267 @@
+/**
+ * @license Copyright (c) 2003-2024, 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 { 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, 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.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 }) {
+    const doc = view.document;
+    // Use a single a single post fixer per—document to update all placeholders.
+    if (!documentPlaceholders.has(doc)) {
+        documentPlaceholders.set(doc, new Map());
+        // If a post-fixer callback makes a change, it should return `true` so other post–fixers
+        // can re–evaluate the document again.
+        doc.registerPostFixer(writer => updateDocumentPlaceholders(doc, writer));
+        // Update placeholders on isComposing state change since rendering is disabled while in composition mode.
+        doc.on('change:isComposing', () => {
+            view.change(writer => updateDocumentPlaceholders(doc, writer));
+        }, { priority: 'high' });
+    }
+    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.
+ *
+ * See {@link module:engine/view/placeholder~enablePlaceholder `enablePlaceholder()`} to learn more.
+ */
+export function disablePlaceholder(view, element) {
+    const doc = element.document;
+    if (!documentPlaceholders.has(doc)) {
+        return;
+    }
+    view.change(writer => {
+        const placeholders = documentPlaceholders.get(doc);
+        const config = placeholders.get(element);
+        writer.removeAttribute('data-placeholder', config.hostElement);
+        hidePlaceholder(writer, config.hostElement);
+        placeholders.delete(element);
+    });
+}
+/**
+ * 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 function showPlaceholder(writer, element) {
+    if (!element.hasClass('ck-placeholder')) {
+        writer.addClass('ck-placeholder', element);
+        return true;
+    }
+    return false;
+}
+/**
+ * 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 function hidePlaceholder(writer, element) {
+    if (element.hasClass('ck-placeholder')) {
+        writer.removeClass('ck-placeholder', element);
+        return true;
+    }
+    return false;
+}
+/**
+ * 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 function needsPlaceholder(element, keepOnFocus) {
+    if (!element.isAttached()) {
+        return false;
+    }
+    // Anything but uiElement(s) counts as content.
+    const hasContent = Array.from(element.getChildren())
+        .some(element => !element.is('uiElement'));
+    if (hasContent) {
+        return false;
+    }
+    const doc = element.document;
+    const viewSelection = doc.selection;
+    const selectionAnchor = viewSelection.anchor;
+    if (doc.isComposing && selectionAnchor && selectionAnchor.parent === element) {
+        return false;
+    }
+    // Skip the focus check and make the placeholder visible already regardless of document focus state.
+    if (keepOnFocus) {
+        return true;
+    }
+    // If the document is blurred.
+    if (!doc.isFocused) {
+        return true;
+    }
+    // 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.
+ *
+ * @returns True if any changes were made to the view document.
+ */
+function updateDocumentPlaceholders(doc, writer) {
+    const placeholders = documentPlaceholders.get(doc);
+    const directHostElements = [];
+    let wasViewModified = false;
+    // First set placeholders on the direct hosts.
+    for (const [element, config] of placeholders) {
+        if (config.isDirectHost) {
+            directHostElements.push(element);
+            if (updatePlaceholder(writer, element, config)) {
+                wasViewModified = true;
+            }
+        }
+    }
+    // Then set placeholders on the indirect hosts but only on those that does not already have an direct host placeholder.
+    for (const [element, config] of placeholders) {
+        if (config.isDirectHost) {
+            continue;
+        }
+        const hostElement = getChildPlaceholderHostSubstitute(element);
+        // When not a direct host, it could happen that there is no child element
+        // capable of displaying a placeholder.
+        if (!hostElement) {
+            continue;
+        }
+        // Don't override placeholder if the host element already has some direct placeholder.
+        if (directHostElements.includes(hostElement)) {
+            continue;
+        }
+        // Update the host element (used for setting and removing the placeholder).
+        config.hostElement = hostElement;
+        if (updatePlaceholder(writer, element, config)) {
+            wasViewModified = true;
+        }
+    }
+    return wasViewModified;
+}
+/**
+ * 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;
+    // This may be necessary when updating the placeholder text to something else.
+    if (hostElement.getAttribute('data-placeholder') !== text) {
+        writer.setAttribute('data-placeholder', text, hostElement);
+        wasViewModified = true;
+    }
+    // If the host element is not a direct host then placeholder is needed only when there is only one element.
+    const isOnlyChild = isDirectHost || element.childCount == 1;
+    if (isOnlyChild && needsPlaceholder(hostElement, config.keepOnFocus)) {
+        if (showPlaceholder(writer, hostElement)) {
+            wasViewModified = true;
+        }
+    }
+    else if (hidePlaceholder(writer, hostElement)) {
+        wasViewModified = true;
+    }
+    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.
+ */
+function getChildPlaceholderHostSubstitute(parent) {
+    if (parent.childCount) {
+        const firstChild = parent.getChild(0);
+        if (firstChild.is('element') && !firstChild.is('uiElement') && !firstChild.is('attributeElement')) {
+            return firstChild;
+        }
+    }
+    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;
+}