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

package/src/model/writer.js

@@ -29,16 +29,18 @@ import { CKEditorError, logWarning, toMap } from '@ckeditor/ckeditor5-utils';
  * The instance of the writer is only available in the {@link module:engine/model/model~Model#change `change()`} or
  * {@link module:engine/model/model~Model#enqueueChange `enqueueChange()`}.
  *
- *		model.change( writer => {
- *			writer.insertText( 'foo', paragraph, 'end' );
- *		} );
+ * ```ts
+ * model.change( writer => {
+ * 	writer.insertText( 'foo', paragraph, 'end' );
+ * } );
+ * ```
  *
  * Note that the writer should never be stored and used outside of the `change()` and
  * `enqueueChange()` blocks.
  *
  * Note that writer's methods do not check the {@link module:engine/model/schema~Schema}. It is possible
  * to create incorrect model structures by using the writer. Read more about in
- * {@glink framework/guides/deep-dive/schema#who-checks-the-schema "Who checks the schema?"}.
+ * {@glink framework/deep-dive/schema#who-checks-the-schema "Who checks the schema?"}.
  *
  * @see module:engine/model/model~Model#change
  * @see module:engine/model/model~Model#enqueueChange
@@ -519,9 +521,6 @@ export default class Writer {
     createRangeOn(element) {
         return this.model.createRangeOn(element);
     }
-    /**
-     * Shortcut for {@link module:engine/model/model~Model#createSelection `Model#createSelection()`}.
-     */
     createSelection(...args) {
         return this.model.createSelection(...args);
     }
@@ -918,60 +917,6 @@ export default class Writer {
         const oldRange = marker.getRange();
         applyMarkerOperation(this, name, oldRange, null, marker.affectsData);
     }
-    /**
-     * Sets the document's selection (ranges and direction) to the specified location based on the given
-     * {@link module:engine/model/selection~Selectable selectable} or creates an empty selection if no arguments were passed.
-     *
-     * ```ts
-     * // Sets selection to the given range.
-     * const range = writer.createRange( start, end );
-     * writer.setSelection( range );
-     *
-     * // Sets selection to given ranges.
-     * const ranges = [ writer.createRange( start1, end2 ), writer.createRange( star2, end2 ) ];
-     * writer.setSelection( ranges );
-     *
-     * // Sets selection to other selection.
-     * const otherSelection = writer.createSelection();
-     * writer.setSelection( otherSelection );
-     *
-     * // Sets selection to the given document selection.
-     * const documentSelection = model.document.selection;
-     * writer.setSelection( documentSelection );
-     *
-     * // Sets collapsed selection at the given position.
-     * const position = writer.createPosition( root, path );
-     * writer.setSelection( position );
-     *
-     * // Sets collapsed selection at the position of the given node and an offset.
-     * writer.setSelection( paragraph, offset );
-     * ```
-     *
-     * Creates a range inside an {@link module:engine/model/element~Element element} which starts before the first child of
-     * that element and ends after the last child of that element.
-     *
-     * ```ts
-     * writer.setSelection( paragraph, 'in' );
-     * ```
-     *
-     * Creates a range on an {@link module:engine/model/item~Item item} which starts before the item and ends just after the item.
-     *
-     * ```ts
-     * writer.setSelection( paragraph, 'on' );
-     *
-     * // Removes all selection's ranges.
-     * writer.setSelection( null );
-     * ```
-     *
-     * `Writer#setSelection()` allow passing additional options (`backward`) as the last argument.
-     *
-     * ```ts
-     * // Sets selection as backward.
-     * writer.setSelection( range, { backward: true } );
-     * ```
-     *
-     * Throws `writer-incorrect-use` error when the writer is used outside the `change()` block.
-     */
     setSelection(...args) {
         this._assertWriterUsedCorrectly();
         this.model.document.selection._setTo(...args);

package/src/view/attributeelement.d.ts

@@ -0,0 +1,108 @@
+/**
+ * @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/attributeelement
+ */
+import Element, { type ElementAttributes } from './element';
+import type Document from './document';
+import type Node from './node';
+/**
+ * Attribute elements are used to represent formatting elements in the view (think – `<b>`, `<span style="font-size: 2em">`, etc.).
+ * Most often they are created when downcasting model text attributes.
+ *
+ * Editing engine does not define a fixed HTML DTD. This is why a feature developer needs to choose between various
+ * types (container element, {@link module:engine/view/attributeelement~AttributeElement attribute element},
+ * {@link module:engine/view/emptyelement~EmptyElement empty element}, etc) when developing a feature.
+ *
+ * To create a new attribute element instance use the
+ * {@link module:engine/view/downcastwriter~DowncastWriter#createAttributeElement `DowncastWriter#createAttributeElement()`} method.
+ */
+export default class AttributeElement extends Element {
+    static readonly DEFAULT_PRIORITY: number;
+    /**
+     * Element priority. Decides in what order elements are wrapped by {@link module:engine/view/downcastwriter~DowncastWriter}.
+     *
+     * @internal
+     * @readonly
+     */
+    _priority: number;
+    /**
+     * Element identifier. If set, it is used by {@link module:engine/view/element~Element#isSimilar},
+     * and then two elements are considered similar if, and only if they have the same `_id`.
+     *
+     * @internal
+     * @readonly
+     */
+    _id: string | number | null;
+    /**
+     * Keeps all the attribute elements that have the same {@link module:engine/view/attributeelement~AttributeElement#id ids}
+     * and still exist in the view tree.
+     *
+     * This property is managed by {@link module:engine/view/downcastwriter~DowncastWriter}.
+     */
+    private readonly _clonesGroup;
+    /**
+     * Creates an attribute element.
+     *
+     * @see module:engine/view/downcastwriter~DowncastWriter#createAttributeElement
+     * @see module:engine/view/element~Element
+     * @protected
+     * @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>);
+    /**
+     * Element priority. Decides in what order elements are wrapped by {@link module:engine/view/downcastwriter~DowncastWriter}.
+     */
+    get priority(): number;
+    /**
+     * Element identifier. If set, it is used by {@link module:engine/view/element~Element#isSimilar},
+     * and then two elements are considered similar if, and only if they have the same `id`.
+     */
+    get id(): string | number | null;
+    /**
+     * Returns all {@link module:engine/view/attributeelement~AttributeElement attribute elements} that has the
+     * same {@link module:engine/view/attributeelement~AttributeElement#id id} and are in the view tree (were not removed).
+     *
+     * Note: If this element has been removed from the tree, returned set will not include it.
+     *
+     * Throws {@link module:utils/ckeditorerror~CKEditorError attribute-element-get-elements-with-same-id-no-id}
+     * if this element has no `id`.
+     *
+     * @returns Set containing all the attribute elements
+     * with the same `id` that were added and not removed from the view tree.
+     */
+    getElementsWithSameId(): Set<AttributeElement>;
+    /**
+     * Checks if this element is similar to other element.
+     *
+     * If none of elements has set {@link module:engine/view/attributeelement~AttributeElement#id}, then both elements
+     * should have the same name, attributes and priority to be considered as similar. Two similar elements can contain
+     * different set of children nodes.
+     *
+     * If at least one element has {@link module:engine/view/attributeelement~AttributeElement#id} set, then both
+     * elements have to have the same {@link module:engine/view/attributeelement~AttributeElement#id} value to be
+     * considered similar.
+     *
+     * Similarity is important for {@link module:engine/view/downcastwriter~DowncastWriter}. For example:
+     *
+     * * two following similar elements can be merged together into one, longer element,
+     * * {@link module:engine/view/downcastwriter~DowncastWriter#unwrap} checks similarity of passed element and processed element to
+     * decide whether processed element should be unwrapped,
+     * * etc.
+     */
+    isSimilar(otherElement: Element): boolean;
+    /**
+     * Clones provided element with priority.
+     *
+     * @internal
+     * @param deep If set to `true` clones element and all its children recursively. When set to `false`,
+     * element will be cloned without any children.
+     * @returns Clone of this element.
+     */
+    _clone(deep?: boolean): this;
+}

package/src/view/attributeelement.js

@@ -19,8 +19,6 @@ const DEFAULT_PRIORITY = 10;
  *
  * To create a new attribute element instance use the
  * {@link module:engine/view/downcastwriter~DowncastWriter#createAttributeElement `DowncastWriter#createAttributeElement()`} method.
- *
- * @extends module:engine/view/element~Element
  */
 export default class AttributeElement extends Element {
     /**
@@ -29,34 +27,26 @@ export default class AttributeElement extends Element {
      * @see module:engine/view/downcastwriter~DowncastWriter#createAttributeElement
      * @see module:engine/view/element~Element
      * @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.
+     * @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 block {@link module:engine/view/filler filler} offset or `null` if block filler is not needed.
-         *
-         * @method #getFillerOffset
-         * @returns {Number|null} Block filler offset or `null` if block filler is not needed.
-         */
-        this.getFillerOffset = getFillerOffset;
+    constructor(document, name, attrs, children) {
+        super(document, name, attrs, children);
         /**
          * Element priority. Decides in what order elements are wrapped by {@link module:engine/view/downcastwriter~DowncastWriter}.
          *
-         * @protected
-         * @member {Number}
+         * @internal
+         * @readonly
          */
         this._priority = DEFAULT_PRIORITY;
         /**
          * Element identifier. If set, it is used by {@link module:engine/view/element~Element#isSimilar},
          * and then two elements are considered similar if, and only if they have the same `_id`.
          *
-         * @protected
-         * @member {String|Number}
+         * @internal
+         * @readonly
          */
         this._id = null;
         /**
@@ -64,17 +54,12 @@ export default class AttributeElement extends Element {
          * and still exist in the view tree.
          *
          * This property is managed by {@link module:engine/view/downcastwriter~DowncastWriter}.
-         *
-         * @protected
-         * @member {Set.<module:engine/view/attributeelement~AttributeElement>|null}
          */
         this._clonesGroup = null;
+        this.getFillerOffset = getFillerOffset;
     }
     /**
      * Element priority. Decides in what order elements are wrapped by {@link module:engine/view/downcastwriter~DowncastWriter}.
-     *
-     * @readonly
-     * @type {Number}
      */
     get priority() {
         return this._priority;
@@ -82,9 +67,6 @@ export default class AttributeElement extends Element {
     /**
      * Element identifier. If set, it is used by {@link module:engine/view/element~Element#isSimilar},
      * and then two elements are considered similar if, and only if they have the same `id`.
-     *
-     * @readonly
-     * @type {String|Number}
      */
     get id() {
         return this._id;
@@ -98,7 +80,7 @@ export default class AttributeElement extends Element {
      * Throws {@link module:utils/ckeditorerror~CKEditorError attribute-element-get-elements-with-same-id-no-id}
      * if this element has no `id`.
      *
-     * @returns {Set.<module:engine/view/attributeelement~AttributeElement>} Set containing all the attribute elements
+     * @returns Set containing all the attribute elements
      * with the same `id` that were added and not removed from the view tree.
      */
     getElementsWithSameId() {
@@ -129,9 +111,6 @@ export default class AttributeElement extends Element {
      * * {@link module:engine/view/downcastwriter~DowncastWriter#unwrap} checks similarity of passed element and processed element to
      * decide whether processed element should be unwrapped,
      * * etc.
-     *
-     * @param {module:engine/view/element~Element} otherElement
-     * @returns {Boolean}
      */
     isSimilar(otherElement) {
         // If any element has an `id` set, just compare the ids.
@@ -143,10 +122,10 @@ export default class AttributeElement extends Element {
     /**
      * Clones provided element with priority.
      *
-     * @protected
-     * @param {Boolean} deep If set to `true` clones element and all its children recursively. When set to `false`,
+     * @internal
+     * @param deep If set to `true` clones element and all its children recursively. When set to `false`,
      * element will be cloned without any children.
-     * @returns {module:engine/view/attributeelement~AttributeElement} Clone of this element.
+     * @returns Clone of this element.
      */
     _clone(deep = false) {
         const cloned = super._clone(deep);
@@ -158,32 +137,8 @@ export default class AttributeElement extends Element {
     }
 }
 AttributeElement.DEFAULT_PRIORITY = DEFAULT_PRIORITY;
-/**
- * Checks whether this object is of the given.
- *
- *		attributeElement.is( 'attributeElement' ); // -> true
- *		attributeElement.is( 'element' ); // -> true
- *		attributeElement.is( 'node' ); // -> true
- *		attributeElement.is( 'view:attributeElement' ); // -> true
- *		attributeElement.is( 'view:element' ); // -> true
- *		attributeElement.is( 'view:node' ); // -> true
- *
- *		attributeElement.is( 'model:element' ); // -> false
- *		attributeElement.is( 'documentFragment' ); // -> false
- *
- * Assuming that the object being checked is an attribute element, you can also check its
- * {@link module:engine/view/attributeelement~AttributeElement#name name}:
- *
- *		attributeElement.is( 'element', 'b' ); // -> true if this is a bold element
- *		attributeElement.is( 'attributeElement', 'b' ); // -> same as above
- *		text.is( 'element', 'b' ); -> 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.
 AttributeElement.prototype.is = function (type, name) {
     if (!name) {
         return type === 'attributeElement' || type === 'view:attributeElement' ||
@@ -197,9 +152,11 @@ AttributeElement.prototype.is = function (type, name) {
             type === 'element' || type === 'view:element');
     }
 };
-// Returns block {@link module:engine/view/filler~Filler filler} offset or `null` if block filler is not needed.
-//
-// @returns {Number|null} Block filler offset or `null` if block filler is not needed.
+/**
+ * Returns block {@link module:engine/view/filler~Filler filler} offset or `null` if block filler is not needed.
+ *
+ * @returns Block filler offset or `null` if block filler is not needed.
+ */
 function getFillerOffset() {
     // <b>foo</b> does not need filler.
     if (nonUiChildrenCount(this)) {
@@ -219,10 +176,9 @@ function getFillerOffset() {
     // Render block filler at the end of element (after all ui elements).
     return this.childCount;
 }
-// Returns total count of children that are not {@link module:engine/view/uielement~UIElement UIElements}.
-//
-// @param {module:engine/view/element~Element} element
-// @returns {Number}
+/**
+ * Returns total count of children that are not {@link module:engine/view/uielement~UIElement UIElements}.
+ */
 function nonUiChildrenCount(element) {
     return Array.from(element.getChildren()).filter(element => !element.is('uiElement')).length;
 }

package/src/view/containerelement.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @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/containerelement
+ */
+import Element, { type ElementAttributes } from './element';
+import type Document from './document';
+import type Node from './node';
+/**
+ * Containers are elements which define document structure. They define boundaries for
+ * {@link module:engine/view/attributeelement~AttributeElement attributes}. They are mostly used for block elements like `<p>` or `<div>`.
+ *
+ * Editing engine does not define a fixed HTML DTD. This is why a feature developer needs to choose between various
+ * types (container element, {@link module:engine/view/attributeelement~AttributeElement attribute element},
+ * {@link module:engine/view/emptyelement~EmptyElement empty element}, etc) when developing a feature.
+ *
+ * The container element should be your default choice when writing a converter, unless:
+ *
+ * * this element represents a model text attribute (then use {@link module:engine/view/attributeelement~AttributeElement}),
+ * * this is an empty element like `<img>` (then use {@link module:engine/view/emptyelement~EmptyElement}),
+ * * this is a root element,
+ * * this is a nested editable element (then use  {@link module:engine/view/editableelement~EditableElement}).
+ *
+ * To create a new container element instance use the
+ * {@link module:engine/view/downcastwriter~DowncastWriter#createContainerElement `DowncastWriter#createContainerElement()`}
+ * method.
+ */
+export default class ContainerElement extends Element {
+    /**
+     * Creates a container element.
+     *
+     * @see module:engine/view/downcastwriter~DowncastWriter#createContainerElement
+     * @see module:engine/view/element~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: Document, name: string, attrs?: ElementAttributes, children?: Node | Iterable<Node>);
+}
+/**
+ * Returns block {@link module:engine/view/filler filler} offset or `null` if block filler is not needed.
+ *
+ * @returns Block filler offset or `null` if block filler is not needed.
+ */
+export declare function getFillerOffset(this: ContainerElement): number | null;

package/src/view/containerelement.js

@@ -24,8 +24,6 @@ import Element from './element';
  * To create a new container element instance use the
  * {@link module:engine/view/downcastwriter~DowncastWriter#createContainerElement `DowncastWriter#createContainerElement()`}
  * method.
- *
- * @extends module:engine/view/element~Element
  */
 export default class ContainerElement extends Element {
     /**
@@ -33,50 +31,19 @@ export default class ContainerElement extends Element {
      *
      * @see module:engine/view/downcastwriter~DowncastWriter#createContainerElement
      * @see module:engine/view/element~Element
-     * @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(...args) {
-        super(...args);
-        /**
-         * Returns block {@link module:engine/view/filler filler} offset or `null` if block filler is not needed.
-         *
-         * @method #getFillerOffset
-         * @returns {Number|null} Block filler offset or `null` if block filler is not needed.
-         */
+    constructor(document, name, attrs, children) {
+        super(document, name, attrs, children);
         this.getFillerOffset = getFillerOffset;
     }
 }
-/**
- * Checks whether this object is of the given.
- *
- *		containerElement.is( 'containerElement' ); // -> true
- *		containerElement.is( 'element' ); // -> true
- *		containerElement.is( 'node' ); // -> true
- *		containerElement.is( 'view:containerElement' ); // -> true
- *		containerElement.is( 'view:element' ); // -> true
- *		containerElement.is( 'view:node' ); // -> true
- *
- *		containerElement.is( 'model:element' ); // -> false
- *		containerElement.is( 'documentFragment' ); // -> false
- *
- * Assuming that the object being checked is a container element, you can also check its
- * {@link module:engine/view/containerelement~ContainerElement#name name}:
- *
- *		containerElement.is( 'element', 'div' ); // -> true if this is a div container element
- *		containerElement.is( 'contaienrElement', 'div' ); // -> same as above
- *		text.is( 'element', 'div' ); -> 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.
 ContainerElement.prototype.is = function (type, name) {
     if (!name) {
         return type === 'containerElement' || type === 'view:containerElement' ||
@@ -93,7 +60,7 @@ ContainerElement.prototype.is = function (type, name) {
 /**
  * Returns block {@link module:engine/view/filler filler} offset or `null` if block filler is not needed.
  *
- * @returns {Number|null} Block filler offset or `null` if block filler is not needed.
+ * @returns Block filler offset or `null` if block filler is not needed.
  */
 export function getFillerOffset() {
     const children = [...this.getChildren()];

package/src/view/datatransfer.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @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/datatransfer
+ */
+type DomDataTransfer = globalThis.DataTransfer;
+/**
+ * A facade over the native [`DataTransfer`](https://developer.mozilla.org/en-US/docs/Web/API/DataTransfer) object.
+ */
+export default class DataTransfer {
+    /**
+     * The array of files created from the native `DataTransfer#files` or `DataTransfer#items`.
+     */
+    private _files;
+    /**
+     * The native DataTransfer object.
+     */
+    private _native;
+    /**
+     * @param nativeDataTransfer The native [`DataTransfer`](https://developer.mozilla.org/en-US/docs/Web/API/DataTransfer) object.
+     * @param options.cacheFiles Whether `files` list should be initialized in the constructor.
+     */
+    constructor(nativeDataTransfer: DomDataTransfer, options?: {
+        cacheFiles?: boolean;
+    });
+    /**
+     * The array of files created from the native `DataTransfer#files` or `DataTransfer#items`.
+     */
+    get files(): Array<File>;
+    /**
+     * Returns an array of available native content types.
+     */
+    get types(): ReadonlyArray<string>;
+    /**
+     * Gets the data from the data transfer by its MIME type.
+     *
+     * ```ts
+     * dataTransfer.getData( 'text/plain' );
+     * ```
+     *
+     * @param type The MIME type. E.g. `text/html` or `text/plain`.
+     */
+    getData(type: string): string;
+    /**
+     * Sets the data in the data transfer.
+     *
+     * @param type The MIME type. E.g. `text/html` or `text/plain`.
+     */
+    setData(type: string, data: string): void;
+    /**
+     * The effect that is allowed for a drag operation.
+     */
+    set effectAllowed(value: EffectAllowed);
+    get effectAllowed(): EffectAllowed;
+    /**
+     * The actual drop effect.
+     */
+    set dropEffect(value: DropEffect);
+    get dropEffect(): DropEffect;
+    /**
+     * Whether the dragging operation was canceled.
+     */
+    get isCanceled(): boolean;
+}
+/**
+ * The effect that is allowed for a drag operation.
+ */
+export type EffectAllowed = DomDataTransfer['effectAllowed'];
+/**
+ * The actual drop effect.
+ */
+export type DropEffect = DomDataTransfer['dropEffect'];
+export {};