@ckeditor/ckeditor5-engine 36.0.0 → 37.0.0-alpha.0

package/src/view/elementdefinition.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @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/elementdefinition
+ */
+import type { ArrayOrItem } from '@ckeditor/ckeditor5-utils';
+/**
+ * A plain object that describes a view element in a way that a concrete, exact view element could be created from that description.
+ *
+ * ```ts
+ * const viewDefinition = {
+ * 	name: 'h1',
+ * 	classes: [ 'foo', 'bar' ]
+ * };
+ * ```
+ *
+ * Above describes a view element:
+ *
+ * ```html
+ * <h1 class="foo bar"></h1>
+ * ```
+ *
+ * An example with styles and attributes:
+ *
+ * ```ts
+ * const viewDefinition = {
+ * 	name: 'span',
+ * 	styles: {
+ * 		'font-size': '12px',
+ * 		'font-weight': 'bold'
+ * 	},
+ * 	attributes: {
+ * 		'data-id': '123'
+ * 	}
+ * };
+ * ```
+ *
+ * Describes:
+ *
+ * ```ts
+ * <span style="font-size:12px;font-weight:bold" data-id="123"></span>
+ * ```
+ */
+export interface ElementObjectDefinition {
+    /**
+     * View element name.
+     */
+    name: string;
+    /**
+     * Class name or array of class names to match. Each name can be provided in a form of string.
+     */
+    classes?: ArrayOrItem<string>;
+    /**
+     * Object with key-value pairs representing styles. Each object key represents style name. Value under that key must be a string.
+     */
+    styles?: Record<string, string>;
+    /**
+     * Object with key-value pairs representing attributes. Each object key represents attribute name.
+     * Value under that key must be a string.
+     */
+    attributes?: Record<string, string>;
+    /**
+     * Element's {@link module:engine/view/attributeelement~AttributeElement#priority priority}.
+     */
+    priority?: number;
+}
+/**
+ * A plain object that describes a view element or element name.
+ *
+ * Elements without attributes can be given simply as a string:
+ *
+ * ```ts
+ * const viewDefinition = 'p';
+ * ```
+ *
+ * Which will be treated as:
+ *
+ * ```ts
+ * const viewDefinition = {
+ * 	name: 'p'
+ * };
+ * ```
+ */
+type ElementDefinition = string | ElementObjectDefinition;
+export default ElementDefinition;

package/src/view/emptyelement.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @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/emptyelement
+ */
+import Element, { type ElementAttributes } from './element';
+import Node from './node';
+import type Document from './document';
+import type Item from './item';
+/**
+ * Empty element class. It is used to represent elements that cannot contain any child nodes (for example `<img>` elements).
+ *
+ * To create a new empty element use the
+ * {@link module:engine/view/downcastwriter~DowncastWriter#createEmptyElement `downcastWriter#createEmptyElement()`} method.
+ */
+export default class EmptyElement extends Element {
+    /**
+     * Creates new instance of EmptyElement.
+     *
+     * Throws {@link module:utils/ckeditorerror~CKEditorError CKEditorError} `view-emptyelement-cannot-add` when third parameter is passed,
+     * to inform that usage of EmptyElement is incorrect (adding child nodes to EmptyElement is forbidden).
+     *
+     * @see module:engine/view/downcastwriter~DowncastWriter#createEmptyElement
+     * @internal
+     * @param document The document instance to which this element belongs.
+     * @param name Node name.
+     * @param attrs Collection of attributes.
+     * @param children A list of nodes to be inserted into created element.
+     */
+    constructor(document: Document, name: string, attributes?: ElementAttributes, children?: Node | Iterable<Node>);
+    /**
+     * Overrides {@link module:engine/view/element~Element#_insertChild} method.
+     * Throws {@link module:utils/ckeditorerror~CKEditorError CKEditorError} `view-emptyelement-cannot-add` to prevent
+     * adding any child nodes to EmptyElement.
+     *
+     * @internal
+     */
+    _insertChild(index: number, items: Item | Iterable<Item>): number;
+}

package/src/view/emptyelement.js

@@ -13,8 +13,6 @@ import { CKEditorError } from '@ckeditor/ckeditor5-utils';
  *
  * To create a new empty element use the
  * {@link module:engine/view/downcastwriter~DowncastWriter#createEmptyElement `downcastWriter#createEmptyElement()`} method.
- *
- * @extends module:engine/view/element~Element
  */
 export default class EmptyElement extends Element {
     /**
@@ -24,21 +22,14 @@ export default class EmptyElement extends Element {
      * to inform that usage of EmptyElement is incorrect (adding child nodes to EmptyElement is forbidden).
      *
      * @see module:engine/view/downcastwriter~DowncastWriter#createEmptyElement
-     * @protected
-     * @param {module:engine/view/document~Document} document The document instance to which this element belongs.
-     * @param {String} name Node name.
-     * @param {Object|Iterable} [attrs] Collection of attributes.
-     * @param {module:engine/view/node~Node|Iterable.<module:engine/view/node~Node>} [children]
-     * A list of nodes to be inserted into created element.
+     * @internal
+     * @param document The document instance to which this element belongs.
+     * @param name Node name.
+     * @param attrs Collection of attributes.
+     * @param children A list of nodes to be inserted into created element.
      */
     constructor(document, name, attributes, children) {
         super(document, name, attributes, children);
-        /**
-         * Returns `null` because filler is not needed for EmptyElements.
-         *
-         * @method #getFillerOffset
-         * @returns {null} Always returns null.
-         */
         this.getFillerOffset = getFillerOffset;
     }
     /**
@@ -46,7 +37,7 @@ export default class EmptyElement extends Element {
      * Throws {@link module:utils/ckeditorerror~CKEditorError CKEditorError} `view-emptyelement-cannot-add` to prevent
      * adding any child nodes to EmptyElement.
      *
-     * @protected
+     * @internal
      */
     _insertChild(index, items) {
         if (items && (items instanceof Node || Array.from(items).length > 0)) {
@@ -60,32 +51,8 @@ export default class EmptyElement extends Element {
         return 0;
     }
 }
-/**
- * Checks whether this object is of the given.
- *
- *		emptyElement.is( 'emptyElement' ); // -> true
- *		emptyElement.is( 'element' ); // -> true
- *		emptyElement.is( 'node' ); // -> true
- *		emptyElement.is( 'view:emptyElement' ); // -> true
- *		emptyElement.is( 'view:element' ); // -> true
- *		emptyElement.is( 'view:node' ); // -> true
- *
- *		emptyElement.is( 'model:element' ); // -> false
- *		emptyElement.is( 'documentFragment' ); // -> false
- *
- * Assuming that the object being checked is an empty element, you can also check its
- * {@link module:engine/view/emptyelement~EmptyElement#name name}:
- *
- *		emptyElement.is( 'element', 'img' ); // -> true if this is a img element
- *		emptyElement.is( 'emptyElement', 'img' ); // -> same as above
- *		text.is( 'element', 'img' ); -> false
- *
- * {@link module:engine/view/node~Node#is Check the entire list of view objects} which implement the `is()` method.
- *
- * @param {String} type Type to check.
- * @param {String} [name] Element name.
- * @returns {Boolean}
- */
+// The magic of type inference using `is` method is centralized in `TypeCheckable` class.
+// Proper overload would interfere with that.
 EmptyElement.prototype.is = function (type, name) {
     if (!name) {
         return type === 'emptyElement' || type === 'view:emptyElement' ||
@@ -98,9 +65,9 @@ EmptyElement.prototype.is = function (type, name) {
             type === 'element' || type === 'view:element');
     }
 };
-// Returns `null` because block filler is not needed for EmptyElements.
-//
-// @returns {null}
+/**
+ * Returns `null` because block filler is not needed for EmptyElements.
+ */
 function getFillerOffset() {
     return null;
 }

package/src/view/filler.d.ts

@@ -0,0 +1,111 @@
+/**
+ * @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 View from './view';
+/**
+ * Set of utilities related to handling block and inline fillers.
+ *
+ * Browsers do not allow to put caret in elements which does not have height. Because of it, we need to fill all
+ * empty elements which should be selectable with elements or characters called "fillers". Unfortunately there is no one
+ * universal filler, this is why two types are uses:
+ *
+ * * Block filler is an element which fill block elements, like `<p>`. CKEditor uses `<br>` as a block filler during the editing,
+ * as browsers do natively. So instead of an empty `<p>` there will be `<p><br></p>`. The advantage of block filler is that
+ * it is transparent for the selection, so when the caret is before the `<br>` and user presses right arrow he will be
+ * moved to the next paragraph, not after the `<br>`. The disadvantage is that it breaks a block, so it can not be used
+ * in the middle of a line of text. The {@link module:engine/view/filler~BR_FILLER `<br>` filler} can be replaced with any other
+ * character in the data output, for instance {@link module:engine/view/filler~NBSP_FILLER non-breaking space} or
+ * {@link module:engine/view/filler~MARKED_NBSP_FILLER marked non-breaking space}.
+ *
+ * * Inline filler is a filler which does not break a line of text, so it can be used inside the text, for instance in the empty
+ * `<b>` surrendered by text: `foo<b></b>bar`, if we want to put the caret there. CKEditor uses a sequence of the zero-width
+ * spaces as an {@link module:engine/view/filler~INLINE_FILLER inline filler} having the predetermined
+ * {@link module:engine/view/filler~INLINE_FILLER_LENGTH length}. A sequence is used, instead of a single character to
+ * avoid treating random zero-width spaces as the inline filler. Disadvantage of the inline filler is that it is not
+ * transparent for the selection. The arrow key moves the caret between zero-width spaces characters, so the additional
+ * code is needed to handle the caret.
+ *
+ * Both inline and block fillers are handled by the {@link module:engine/view/renderer~Renderer renderer} and are not present in the
+ * view.
+ *
+ * @module engine/view/filler
+ */
+/**
+ * Non-breaking space filler creator. This function creates the `&nbsp;` text node.
+ * It defines how the filler is created.
+ *
+ * @see module:engine/view/filler~MARKED_NBSP_FILLER
+ * @see module:engine/view/filler~BR_FILLER
+ */
+export declare const NBSP_FILLER: (domDocument: Document) => Text;
+/**
+ * Marked non-breaking space filler creator. This function creates the `<span data-cke-filler="true">&nbsp;</span>` element.
+ * It defines how the filler is created.
+ *
+ * @see module:engine/view/filler~NBSP_FILLER
+ * @see module:engine/view/filler~BR_FILLER
+ */
+export declare const MARKED_NBSP_FILLER: (domDocument: Document) => HTMLSpanElement;
+/**
+ * `<br>` filler creator. This function creates the `<br data-cke-filler="true">` element.
+ * It defines how the filler is created.
+ *
+ * @see module:engine/view/filler~NBSP_FILLER
+ * @see module:engine/view/filler~MARKED_NBSP_FILLER
+ */
+export declare const BR_FILLER: (domDocument: Document) => HTMLBRElement;
+/**
+ * Length of the {@link module:engine/view/filler~INLINE_FILLER INLINE_FILLER}.
+ */
+export declare const INLINE_FILLER_LENGTH = 7;
+/**
+ * Inline filler which is a sequence of the word joiners.
+ */
+export declare const INLINE_FILLER: string;
+/**
+ * Checks if the node is a text node which starts with the {@link module:engine/view/filler~INLINE_FILLER inline filler}.
+ *
+ * ```ts
+ * startsWithFiller( document.createTextNode( INLINE_FILLER ) ); // true
+ * startsWithFiller( document.createTextNode( INLINE_FILLER + 'foo' ) ); // true
+ * startsWithFiller( document.createTextNode( 'foo' ) ); // false
+ * startsWithFiller( document.createElement( 'p' ) ); // false
+ * ```
+ *
+ * @param domNode DOM node.
+ * @returns True if the text node starts with the {@link module:engine/view/filler~INLINE_FILLER inline filler}.
+ */
+export declare function startsWithFiller(domNode: Node): boolean;
+/**
+ * Checks if the text node contains only the {@link module:engine/view/filler~INLINE_FILLER inline filler}.
+ *
+ * ```ts
+ * isInlineFiller( document.createTextNode( INLINE_FILLER ) ); // true
+ * isInlineFiller( document.createTextNode( INLINE_FILLER + 'foo' ) ); // false
+ * ```
+ *
+ * @param domText DOM text node.
+ * @returns True if the text node contains only the {@link module:engine/view/filler~INLINE_FILLER inline filler}.
+ */
+export declare function isInlineFiller(domText: Text): boolean;
+/**
+ * Get string data from the text node, removing an {@link module:engine/view/filler~INLINE_FILLER inline filler} from it,
+ * if text node contains it.
+ *
+ * ```ts
+ * getDataWithoutFiller( document.createTextNode( INLINE_FILLER + 'foo' ) ) == 'foo' // true
+ * getDataWithoutFiller( document.createTextNode( 'foo' ) ) == 'foo' // true
+ * ```
+ *
+ * @param domText DOM text node, possible with inline filler.
+ * @returns Data without filler.
+ */
+export declare function getDataWithoutFiller(domText: Text): string;
+/**
+ * Assign key observer which move cursor from the end of the inline filler to the beginning of it when
+ * the left arrow is pressed, so the filler does not break navigation.
+ *
+ * @param view View controller instance we should inject quirks handling on.
+ */
+export declare function injectQuirksHandling(view: View): void;

package/src/view/filler.js

@@ -37,7 +37,6 @@ import { keyCodes, isText } from '@ckeditor/ckeditor5-utils';
  *
  * @see module:engine/view/filler~MARKED_NBSP_FILLER
  * @see module:engine/view/filler~BR_FILLER
- * @function
  */
 export const NBSP_FILLER = (domDocument) => domDocument.createTextNode('\u00A0');
 /**
@@ -46,7 +45,6 @@ export const NBSP_FILLER = (domDocument) => domDocument.createTextNode('\u00A0')
  *
  * @see module:engine/view/filler~NBSP_FILLER
  * @see module:engine/view/filler~BR_FILLER
- * @function
  */
 export const MARKED_NBSP_FILLER = (domDocument) => {
     const span = domDocument.createElement('span');
@@ -60,7 +58,6 @@ export const MARKED_NBSP_FILLER = (domDocument) => {
  *
  * @see module:engine/view/filler~NBSP_FILLER
  * @see module:engine/view/filler~MARKED_NBSP_FILLER
- * @function
  */
 export const BR_FILLER = (domDocument) => {
     const fillerBr = domDocument.createElement('br');
@@ -73,20 +70,20 @@ export const BR_FILLER = (domDocument) => {
 export const INLINE_FILLER_LENGTH = 7;
 /**
  * Inline filler which is a sequence of the word joiners.
- *
- * @type {String}
  */
 export const INLINE_FILLER = '\u2060'.repeat(INLINE_FILLER_LENGTH);
 /**
  * Checks if the node is a text node which starts with the {@link module:engine/view/filler~INLINE_FILLER inline filler}.
  *
- *		startsWithFiller( document.createTextNode( INLINE_FILLER ) ); // true
- *		startsWithFiller( document.createTextNode( INLINE_FILLER + 'foo' ) ); // true
- *		startsWithFiller( document.createTextNode( 'foo' ) ); // false
- *		startsWithFiller( document.createElement( 'p' ) ); // false
+ * ```ts
+ * startsWithFiller( document.createTextNode( INLINE_FILLER ) ); // true
+ * startsWithFiller( document.createTextNode( INLINE_FILLER + 'foo' ) ); // true
+ * startsWithFiller( document.createTextNode( 'foo' ) ); // false
+ * startsWithFiller( document.createElement( 'p' ) ); // false
+ * ```
  *
- * @param {Node} domNode DOM node.
- * @returns {Boolean} True if the text node starts with the {@link module:engine/view/filler~INLINE_FILLER inline filler}.
+ * @param domNode DOM node.
+ * @returns True if the text node starts with the {@link module:engine/view/filler~INLINE_FILLER inline filler}.
  */
 export function startsWithFiller(domNode) {
     return isText(domNode) && (domNode.data.substr(0, INLINE_FILLER_LENGTH) === INLINE_FILLER);
@@ -94,11 +91,13 @@ export function startsWithFiller(domNode) {
 /**
  * Checks if the text node contains only the {@link module:engine/view/filler~INLINE_FILLER inline filler}.
  *
- *		isInlineFiller( document.createTextNode( INLINE_FILLER ) ); // true
- *		isInlineFiller( document.createTextNode( INLINE_FILLER + 'foo' ) ); // false
+ * ```ts
+ * isInlineFiller( document.createTextNode( INLINE_FILLER ) ); // true
+ * isInlineFiller( document.createTextNode( INLINE_FILLER + 'foo' ) ); // false
+ * ```
  *
- * @param {Text} domText DOM text node.
- * @returns {Boolean} True if the text node contains only the {@link module:engine/view/filler~INLINE_FILLER inline filler}.
+ * @param domText DOM text node.
+ * @returns True if the text node contains only the {@link module:engine/view/filler~INLINE_FILLER inline filler}.
  */
 export function isInlineFiller(domText) {
     return domText.data.length == INLINE_FILLER_LENGTH && startsWithFiller(domText);
@@ -107,11 +106,13 @@ export function isInlineFiller(domText) {
  * Get string data from the text node, removing an {@link module:engine/view/filler~INLINE_FILLER inline filler} from it,
  * if text node contains it.
  *
- *		getDataWithoutFiller( document.createTextNode( INLINE_FILLER + 'foo' ) ) == 'foo' // true
- *		getDataWithoutFiller( document.createTextNode( 'foo' ) ) == 'foo' // true
+ * ```ts
+ * getDataWithoutFiller( document.createTextNode( INLINE_FILLER + 'foo' ) ) == 'foo' // true
+ * getDataWithoutFiller( document.createTextNode( 'foo' ) ) == 'foo' // true
+ * ```
  *
- * @param {Text} domText DOM text node, possible with inline filler.
- * @returns {String} Data without filler.
+ * @param domText DOM text node, possible with inline filler.
+ * @returns Data without filler.
  */
 export function getDataWithoutFiller(domText) {
     if (startsWithFiller(domText)) {
@@ -125,12 +126,14 @@ export function getDataWithoutFiller(domText) {
  * Assign key observer which move cursor from the end of the inline filler to the beginning of it when
  * the left arrow is pressed, so the filler does not break navigation.
  *
- * @param {module:engine/view/view~View} view View controller instance we should inject quirks handling on.
+ * @param view View controller instance we should inject quirks handling on.
  */
 export function injectQuirksHandling(view) {
     view.document.on('arrowKey', jumpOverInlineFiller, { priority: 'low' });
 }
-// Move cursor from the end of the inline filler to the beginning of it when, so the filler does not break navigation.
+/**
+ * Move cursor from the end of the inline filler to the beginning of it when, so the filler does not break navigation.
+ */
 function jumpOverInlineFiller(evt, data) {
     if (data.keyCode == keyCodes.arrowleft) {
         const domSelection = data.domTarget.ownerDocument.defaultView.getSelection();

package/src/view/item.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @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 Node from './node';
+import type TextProxy from './textproxy';
+/**
+ * @module engine/view/item
+ */
+/**
+ * Item is a {@link module:engine/view/node~Node Node} or {@link module:engine/view/textproxy~TextProxy TextProxy}.
+ */
+type Item = Node | TextProxy;
+export default Item;