@ckeditor/ckeditor5-engine 36.0.1 → 37.0.0-alpha.1

package/src/view/rawelement.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @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/rawelement
+ */
+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.
+ *
+ * The raw elements work as data containers ("wrappers", "sandboxes") but their children are not managed or
+ * even recognized by the editor. This encapsulation allows integrations to maintain custom DOM structures
+ * in the editor content without, for instance, worrying about compatibility with other editor features.
+ * Raw elements are a perfect tool for integration with external frameworks and data sources.
+ *
+ * Unlike {@link module:engine/view/uielement~UIElement UI elements}, raw elements act like real editor
+ * content (similar to {@link module:engine/view/containerelement~ContainerElement} or
+ * {@link module:engine/view/emptyelement~EmptyElement}), they are considered by the editor selection and
+ * {@link module:widget/utils~toWidget they can work as widgets}.
+ *
+ * To create a new raw element, use the
+ * {@link module:engine/view/downcastwriter~DowncastWriter#createRawElement `downcastWriter#createRawElement()`} method.
+ */
+export default class RawElement extends Element {
+    /**
+     * Creates a new instance of a raw element.
+     *
+     * Throws the `view-rawelement-cannot-add` {@link module:utils/ckeditorerror~CKEditorError CKEditorError} when the `children`
+     * parameter is passed to inform that the usage of `RawElement` is incorrect (adding child nodes to `RawElement` is forbidden).
+     *
+     * @see module:engine/view/downcastwriter~DowncastWriter#createRawElement
+     * @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, attrs?: ElementAttributes, children?: Node | Iterable<Node>);
+    /**
+     * Overrides the {@link module:engine/view/element~Element#_insertChild} method.
+     * Throws the `view-rawelement-cannot-add` {@link module:utils/ckeditorerror~CKEditorError CKEditorError} to prevent
+     * adding any child nodes to a raw element.
+     *
+     * @internal
+     */
+    _insertChild(index: number, items: Item | Iterable<Item>): number;
+    /**
+     * This allows rendering the children of a {@link module:engine/view/rawelement~RawElement} on the DOM level.
+     * This method is called by the {@link module:engine/view/domconverter~DomConverter} with the raw DOM element
+     * passed as an argument, leaving the number and shape of the children up to the integrator.
+     *
+     * This method **must be defined** for the raw element to work:
+     *
+     * ```ts
+     * const myRawElement = downcastWriter.createRawElement( 'div' );
+     *
+     * myRawElement.render = function( domElement, domConverter ) {
+     * 	domConverter.setContentOf( domElement, '<b>This is the raw content of myRawElement.</b>' );
+     * };
+     * ```
+     *
+     * @param domElement The native DOM element representing the raw view element.
+     * @param domConverter Instance of the DomConverter used to optimize the output.
+     */
+    render(domElement: DomElement, domConverter: DomConverter): void;
+}
+export {};

package/src/view/rawelement.js

@@ -2,6 +2,7 @@
  * @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
  */
+/* eslint-disable @typescript-eslint/no-unused-vars */
 /**
  * @module engine/view/rawelement
  */
@@ -23,8 +24,6 @@ import { CKEditorError } from '@ckeditor/ckeditor5-utils';
  *
  * To create a new raw element, use the
  * {@link module:engine/view/downcastwriter~DowncastWriter#createRawElement `downcastWriter#createRawElement()`} method.
- *
- * @extends module:engine/view/element~Element
  */
 export default class RawElement extends Element {
     /**
@@ -34,21 +33,15 @@ export default class RawElement extends Element {
      * parameter is passed to inform that the usage of `RawElement` is incorrect (adding child nodes to `RawElement` is forbidden).
      *
      * @see module:engine/view/downcastwriter~DowncastWriter#createRawElement
-     * @protected
-     * @param {module:engine/view/document~Document} document The document instance to which this element belongs.
-     * @param {String} name A node name.
-     * @param {Object|Iterable} [attrs] The collection of attributes.
-     * @param {module:engine/view/node~Node|Iterable.<module:engine/view/node~Node>} [children]
-     * A list of nodes to be inserted into the 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(...args) {
-        super(...args);
-        /**
-         * Returns `null` because filler is not needed for raw elements.
-         *
-         * @method #getFillerOffset
-         * @returns {null} Always returns null.
-         */
+    constructor(document, name, attrs, children) {
+        super(document, name, attrs, children);
+        // Returns `null` because filler is not needed for raw elements.
         this.getFillerOffset = getFillerOffset;
     }
     /**
@@ -56,7 +49,7 @@ export default class RawElement extends Element {
      * Throws the `view-rawelement-cannot-add` {@link module:utils/ckeditorerror~CKEditorError CKEditorError} to prevent
      * adding any child nodes to a raw element.
      *
-     * @protected
+     * @internal
      */
     _insertChild(index, items) {
         if (items && (items instanceof Node || Array.from(items).length > 0)) {
@@ -69,35 +62,28 @@ export default class RawElement extends Element {
         }
         return 0;
     }
-    render() { }
+    /**
+     * This allows rendering the children of a {@link module:engine/view/rawelement~RawElement} on the DOM level.
+     * This method is called by the {@link module:engine/view/domconverter~DomConverter} with the raw DOM element
+     * passed as an argument, leaving the number and shape of the children up to the integrator.
+     *
+     * This method **must be defined** for the raw element to work:
+     *
+     * ```ts
+     * const myRawElement = downcastWriter.createRawElement( 'div' );
+     *
+     * myRawElement.render = function( domElement, domConverter ) {
+     * 	domConverter.setContentOf( domElement, '<b>This is the raw content of myRawElement.</b>' );
+     * };
+     * ```
+     *
+     * @param domElement The native DOM element representing the raw view element.
+     * @param domConverter Instance of the DomConverter used to optimize the output.
+     */
+    render(domElement, domConverter) { }
 }
-/**
- * Checks whether this object is of the given type or name.
- *
- *		rawElement.is( 'rawElement' ); // -> true
- *		rawElement.is( 'element' ); // -> true
- *		rawElement.is( 'node' ); // -> true
- *		rawElement.is( 'view:rawElement' ); // -> true
- *		rawElement.is( 'view:element' ); // -> true
- *		rawElement.is( 'view:node' ); // -> true
- *
- *		rawElement.is( 'model:element' ); // -> false
- *		rawElement.is( 'documentFragment' ); // -> false
- *
- * Assuming that the object being checked is a raw element, you can also check its
- * {@link module:engine/view/rawelement~RawElement#name name}:
- *
- *		rawElement.is( 'img' ); // -> true if this is an img element
- *		rawElement.is( 'rawElement', 'img' ); // -> same as above
- *		text.is( 'img' ); -> false
- *
- * {@link module:engine/view/node~Node#is Check the entire list of view objects} which implement the `is()` method.
- *
- * @param {String} type The type to check when the `name` parameter is present.
- * Otherwise, it acts like the `name` parameter.
- * @param {String} [name] The element name.
- * @returns {Boolean}
- */
+// The magic of type inference using `is` method is centralized in `TypeCheckable` class.
+// Proper overload would interfere with that.
 RawElement.prototype.is = function (type, name) {
     if (!name) {
         return type === 'rawElement' || type === 'view:rawElement' ||
@@ -111,9 +97,9 @@ RawElement.prototype.is = function (type, name) {
             type === 'element' || type === 'view:element');
     }
 };
-// Returns `null` because block filler is not needed for raw elements.
-//
-// @returns {null}
+/**
+ * Returns `null` because block filler is not needed for raw elements.
+ */
 function getFillerOffset() {
     return null;
 }

package/src/view/renderer.d.ts

@@ -0,0 +1,265 @@
+/**
+ * @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';
+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: {
+    new (): import("@ckeditor/ckeditor5-utils").Observable;
+    prototype: import("@ckeditor/ckeditor5-utils").Observable;
+};
+/**
+ * Renderer is responsible for updating the DOM structure and the DOM selection based on
+ * the {@link module:engine/view/renderer~Renderer#markToSync information about updated view nodes}.
+ * In other words, it renders the view to the DOM.
+ *
+ * Its main responsibility is to make only the necessary, minimal changes to the DOM. However, unlike in many
+ * virtual DOM implementations, the primary reason for doing minimal changes is not the performance but ensuring
+ * that native editing features such as text composition, autocompletion, spell checking, selection's x-index are
+ * affected as little as possible.
+ *
+ * Renderer uses {@link module:engine/view/domconverter~DomConverter} to transform view nodes and positions
+ * to and from the DOM.
+ */
+export default class Renderer extends Renderer_base {
+    /**
+     * Set of DOM Documents instances.
+     */
+    readonly domDocuments: Set<DomDocument>;
+    /**
+     * Converter instance.
+     */
+    readonly domConverter: DomConverter;
+    /**
+     * Set of nodes which attributes changed and may need to be rendered.
+     */
+    readonly markedAttributes: Set<ViewElement>;
+    /**
+     * Set of elements which child lists changed and may need to be rendered.
+     */
+    readonly markedChildren: Set<ViewElement>;
+    /**
+     * Set of text nodes which text data changed and may need to be rendered.
+     */
+    readonly markedTexts: Set<ViewNode>;
+    /**
+     * View selection. Renderer updates DOM selection based on the view selection.
+     */
+    readonly selection: DocumentSelection;
+    /**
+     * Indicates if the view document is focused and selection can be rendered. Selection will not be rendered if
+     * this is set to `false`.
+     *
+     * @observable
+     */
+    readonly isFocused: boolean;
+    /**
+     * Indicates whether the user is making a selection in the document (e.g. holding the mouse button and moving the cursor).
+     * When they stop selecting, the property goes back to `false`.
+     *
+     * Note: In some browsers, the renderer will stop rendering the selection and inline fillers while the user is making
+     * a selection to avoid glitches in DOM selection
+     * (https://github.com/ckeditor/ckeditor5/issues/10562, https://github.com/ckeditor/ckeditor5/issues/10723).
+     *
+     * @observable
+     */
+    readonly isSelecting: boolean;
+    /**
+     * True if composition is in progress inside the document.
+     *
+     * This property is bound to the {@link module:engine/view/document~Document#isComposing `Document#isComposing`} property.
+     *
+     * @observable
+     */
+    readonly isComposing: boolean;
+    /**
+     * The text node in which the inline filler was rendered.
+     */
+    private _inlineFiller;
+    /**
+     * DOM element containing fake selection.
+     */
+    private _fakeSelectionContainer;
+    /**
+     * Creates a renderer instance.
+     *
+     * @param domConverter Converter instance.
+     * @param selection View selection.
+     */
+    constructor(domConverter: DomConverter, selection: DocumentSelection);
+    /**
+     * Marks a view node to be updated in the DOM by {@link #render `render()`}.
+     *
+     * Note that only view nodes whose parents have corresponding DOM elements need to be marked to be synchronized.
+     *
+     * @see #markedAttributes
+     * @see #markedChildren
+     * @see #markedTexts
+     *
+     * @param type Type of the change.
+     * @param node ViewNode to be marked.
+     */
+    markToSync(type: ChangeType, node: ViewNode): void;
+    /**
+     * Renders all buffered changes ({@link #markedAttributes}, {@link #markedChildren} and {@link #markedTexts}) and
+     * the current view selection (if needed) to the DOM by applying a minimal set of changes to it.
+     *
+     * Renderer tries not to break the text composition (e.g. IME) and x-index of the selection,
+     * so it does as little as it is needed to update the DOM.
+     *
+     * Renderer also handles {@link module:engine/view/filler fillers}. Especially, it checks if the inline filler is needed
+     * at the selection position and adds or removes it. To prevent breaking text composition inline filler will not be
+     * removed as long as the selection is in the text node which needed it at first.
+     */
+    render(): void;
+    /**
+     * Updates mappings of view element's children.
+     *
+     * Children that were replaced in the view structure by similar elements (same tag name) are treated as 'replaced'.
+     * This means that their mappings can be updated so the new view elements are mapped to the existing DOM elements.
+     * Thanks to that these elements do not need to be re-rendered completely.
+     *
+     * @param viewElement The view element whose children mappings will be updated.
+     */
+    private _updateChildrenMappings;
+    /**
+     * Updates mappings of a given view element.
+     *
+     * @param viewElement The view element whose mappings will be updated.
+     * @param domElement The DOM element representing the given view element.
+     */
+    private _updateElementMappings;
+    /**
+     * Gets the position of the inline filler based on the current selection.
+     * Here, we assume that we know that the filler is needed and
+     * {@link #_isSelectionInInlineFiller is at the selection position}, and, since it is needed,
+     * it is somewhere at the selection position.
+     *
+     * Note: The filler position cannot be restored based on the filler's DOM text node, because
+     * when this method is called (before rendering), the bindings will often be broken. View-to-DOM
+     * bindings are only dependable after rendering.
+     */
+    private _getInlineFillerPosition;
+    /**
+     * Returns `true` if the selection has not left the inline filler's text node.
+     * If it is `true`, it means that the filler had been added for a reason and the selection did not
+     * leave the filler's text node. For example, the user can be in the middle of a composition so it should not be touched.
+     *
+     * @returns `true` if the inline filler and selection are in the same place.
+     */
+    private _isSelectionInInlineFiller;
+    /**
+     * Removes the inline filler.
+     */
+    private _removeInlineFiller;
+    /**
+     * Checks if the inline {@link module:engine/view/filler filler} should be added.
+     *
+     * @returns `true` if the inline filler should be added.
+     */
+    private _needsInlineFillerAtSelection;
+    /**
+     * Checks if text needs to be updated and possibly updates it.
+     *
+     * @param viewText View text to update.
+     * @param options.inlineFillerPosition The position where the inline filler should be rendered.
+     */
+    private _updateText;
+    /**
+     * Checks if attribute list needs to be updated and possibly updates it.
+     *
+     * @param viewElement The view element to update.
+     */
+    private _updateAttrs;
+    /**
+     * Checks if elements child list needs to be updated and possibly updates it.
+     *
+     * Note that on Android, to reduce the risk of composition breaks, it tries to update data of an existing
+     * child text nodes instead of replacing them completely.
+     *
+     * @param viewElement View element to update.
+     * @param options.inlineFillerPosition The position where the inline filler should be rendered.
+     */
+    private _updateChildren;
+    /**
+     * Shorthand for diffing two arrays or node lists of DOM nodes.
+     *
+     * @param actualDomChildren Actual DOM children
+     * @param expectedDomChildren Expected DOM children.
+     * @returns The list of actions based on the {@link module:utils/diff~diff} function.
+     */
+    private _diffNodeLists;
+    /**
+     * Finds DOM nodes that were replaced with the similar nodes (same tag name) in the view. All nodes are compared
+     * within one `insert`/`delete` action group, for example:
+     *
+     * ```
+     * Actual DOM:		<p><b>Foo</b>Bar<i>Baz</i><b>Bax</b></p>
+     * Expected DOM:	<p>Bar<b>123</b><i>Baz</i><b>456</b></p>
+     * Input actions:	[ insert, insert, delete, delete, equal, insert, delete ]
+     * Output actions:	[ insert, replace, delete, equal, replace ]
+     * ```
+     *
+     * @param actions Actions array which is a result of the {@link module:utils/diff~diff} function.
+     * @param actualDom Actual DOM children
+     * @param expectedDom Expected DOM children.
+     * @param options Options
+     * @param options.replaceText Mark text nodes replacement.
+     * @returns Actions array modified with the `replace` actions.
+     */
+    private _findReplaceActions;
+    /**
+     * Marks text nodes to be synchronized.
+     *
+     * If a text node is passed, it will be marked. If an element is passed, all descendant text nodes inside it will be marked.
+     *
+     * @param viewNode View node to sync.
+     */
+    private _markDescendantTextToSync;
+    /**
+     * Checks if the selection needs to be updated and possibly updates it.
+     */
+    private _updateSelection;
+    /**
+     * Updates the fake selection.
+     *
+     * @param domRoot A valid DOM root where the fake selection container should be added.
+     */
+    private _updateFakeSelection;
+    /**
+     * Updates the DOM selection.
+     *
+     * @param domRoot A valid DOM root where the DOM selection should be rendered.
+     */
+    private _updateDomSelection;
+    /**
+     * Checks whether a given DOM selection needs to be updated.
+     *
+     * @param domSelection The DOM selection to check.
+     */
+    private _domSelectionNeedsUpdate;
+    /**
+     * Checks whether the fake selection needs to be updated.
+     *
+     * @param domRoot A valid DOM root where a new fake selection container should be added.
+     */
+    private _fakeSelectionNeedsUpdate;
+    /**
+     * Removes the DOM selection.
+     */
+    private _removeDomSelection;
+    /**
+     * Removes the fake selection.
+     */
+    private _removeFakeSelection;
+    /**
+     * Checks if focus needs to be updated and possibly updates it.
+     */
+    private _updateFocus;
+}
+export {};