@ckeditor/ckeditor5-engine 0.0.0-internal-20241017.0

package/src/view/elementdefinition.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @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/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/elementdefinition.js

@@ -0,0 +1,5 @@
+/**
+ * @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
+ */
+export {};

package/src/view/emptyelement.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @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/emptyelement
+ */
+import Element, { type ElementAttributes } from './element.js';
+import Node from './node.js';
+import type Document from './document.js';
+import type Item from './item.js';
+/**
+ * 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

@@ -0,0 +1,73 @@
+/**
+ * @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/emptyelement
+ */
+import Element from './element.js';
+import Node from './node.js';
+import { CKEditorError } from '@ckeditor/ckeditor5-utils';
+/**
+ * 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, name, attributes, children) {
+        super(document, name, attributes, children);
+        this.getFillerOffset = getFillerOffset;
+    }
+    /**
+     * 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, items) {
+        if (items && (items instanceof Node || Array.from(items).length > 0)) {
+            /**
+             * Cannot add children to {@link module:engine/view/emptyelement~EmptyElement}.
+             *
+             * @error view-emptyelement-cannot-add
+             */
+            throw new CKEditorError('view-emptyelement-cannot-add', [this, items]);
+        }
+        return 0;
+    }
+}
+// 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' ||
+            // From super.is(). This is highly utilised method and cannot call super. See ckeditor/ckeditor5#6529.
+            type === 'element' || type === 'view:element' ||
+            type === 'node' || type === 'view:node';
+    }
+    else {
+        return name === this.name && (type === 'emptyElement' || type === 'view:emptyElement' ||
+            type === 'element' || type === 'view:element');
+    }
+};
+/**
+ * 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-2024, 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.js';
+/**
+ * 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 | string): 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): 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

@@ -0,0 +1,150 @@
+/**
+ * @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 { keyCodes, isText } from '@ckeditor/ckeditor5-utils';
+/**
+ * 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 const NBSP_FILLER = (domDocument) => domDocument.createTextNode('\u00A0');
+/**
+ * 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 const MARKED_NBSP_FILLER = (domDocument) => {
+    const span = domDocument.createElement('span');
+    span.dataset.ckeFiller = 'true';
+    span.innerText = '\u00A0';
+    return span;
+};
+/**
+ * `<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 const BR_FILLER = (domDocument) => {
+    const fillerBr = domDocument.createElement('br');
+    fillerBr.dataset.ckeFiller = 'true';
+    return fillerBr;
+};
+/**
+ * Length of the {@link module:engine/view/filler~INLINE_FILLER INLINE_FILLER}.
+ */
+export const INLINE_FILLER_LENGTH = 7;
+/**
+ * Inline filler which is a sequence of the word joiners.
+ */
+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}.
+ *
+ * ```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 function startsWithFiller(domNode) {
+    if (typeof domNode == 'string') {
+        return domNode.substr(0, INLINE_FILLER_LENGTH) === INLINE_FILLER;
+    }
+    return isText(domNode) && (domNode.data.substr(0, INLINE_FILLER_LENGTH) === INLINE_FILLER);
+}
+/**
+ * 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 function isInlineFiller(domText) {
+    return domText.data.length == INLINE_FILLER_LENGTH && startsWithFiller(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.
+ *
+ * ```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 function getDataWithoutFiller(domText) {
+    const data = typeof domText == 'string' ? domText : domText.data;
+    if (startsWithFiller(domText)) {
+        return data.slice(INLINE_FILLER_LENGTH);
+    }
+    return data;
+}
+/**
+ * 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 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.
+ */
+function jumpOverInlineFiller(evt, data) {
+    if (data.keyCode == keyCodes.arrowleft) {
+        const domSelection = data.domTarget.ownerDocument.defaultView.getSelection();
+        if (domSelection.rangeCount == 1 && domSelection.getRangeAt(0).collapsed) {
+            const domParent = domSelection.getRangeAt(0).startContainer;
+            const domOffset = domSelection.getRangeAt(0).startOffset;
+            if (startsWithFiller(domParent) && domOffset <= INLINE_FILLER_LENGTH) {
+                domSelection.collapse(domParent, 0);
+            }
+        }
+    }
+}

package/src/view/item.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @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 type Node from './node.js';
+import type TextProxy from './textproxy.js';
+/**
+ * @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;

package/src/view/item.js

@@ -0,0 +1,5 @@
+/**
+ * @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
+ */
+export {};