@ckeditor/ckeditor5-engine 39.0.0 → 39.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-engine",
-  "version": "39.0.0",
+  "version": "39.0.1",
   "description": "The editing engine of CKEditor 5 – the best browser-based rich text editor.",
   "keywords": [
     "wysiwyg",
@@ -23,7 +23,7 @@
   ],
   "main": "src/index.js",
   "dependencies": {
-    "@ckeditor/ckeditor5-utils": "39.0.0",
+    "@ckeditor/ckeditor5-utils": "39.0.1",
     "lodash-es": "4.17.21"
   },
   "engines": {

package/src/view/placeholder.d.ts

@@ -25,12 +25,15 @@ import type View from './view';
  * 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, isDirectHost, keepOnFocus }: {
+export declare function enablePlaceholder({ view, element, text, isDirectHost, keepOnFocus }: {
     view: View;
     element: PlaceholderableElement | EditableElement;
     isDirectHost?: boolean;
+    text?: string;
     keepOnFocus?: boolean;
 }): void;
 /**

package/src/view/placeholder.js

@@ -6,8 +6,10 @@
  * @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.
@@ -23,9 +25,11 @@ const documentPlaceholders = new WeakMap();
  * 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, isDirectHost = true, keepOnFocus = false }) {
+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)) {
@@ -46,6 +50,12 @@ export function enablePlaceholder({ view, element, isDirectHost = true, keepOnFo
     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, {
@@ -237,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;
+}