@ckeditor/ckeditor5-engine 35.3.2 → 36.0.0

package/src/model/liverange.js

@@ -1,13 +1,12 @@
 /**
- * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @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 new-cap */
 /**
  * @module engine/model/liverange
  */
 import Range from './range';
-import EmitterMixin from '@ckeditor/ckeditor5-utils/src/emittermixin';
+import { EmitterMixin } from '@ckeditor/ckeditor5-utils';
 /**
  * `LiveRange` is a type of {@link module:engine/model/range~Range Range}
  * that updates itself as {@link module:engine/model/document~Document document}
@@ -36,47 +35,28 @@ export default class LiveRange extends EmitterMixin(Range) {
     }
     /**
      * Creates a {@link module:engine/model/range~Range range instance} that is equal to this live range.
-     *
-     * @returns {module:engine/model/range~Range}
      */
     toRange() {
         return new Range(this.start, this.end);
     }
     /**
      * Creates a `LiveRange` instance that is equal to the given range.
-     *
-     * @param {module:engine/model/range~Range} range
-     * @returns {module:engine/model/liverange~LiveRange}
      */
     static fromRange(range) {
         return new LiveRange(range.start, range.end);
     }
 }
-/**
- * Checks whether this object is of the given.
- *
- *		liveRange.is( 'range' ); // -> true
- *		liveRange.is( 'model:range' ); // -> true
- *		liveRange.is( 'liveRange' ); // -> true
- *		liveRange.is( 'model:liveRange' ); // -> true
- *
- *		liveRange.is( 'view:range' ); // -> false
- *		liveRange.is( 'documentSelection' ); // -> false
- *
- * {@link module:engine/model/node~Node#is Check the entire list of model objects} which implement the `is()` method.
- *
- * @param {String} type
- * @returns {Boolean}
- */
+// The magic of type inference using `is` method is centralized in `TypeCheckable` class.
+// Proper overload would interfere with that.
 LiveRange.prototype.is = function (type) {
     return type === 'liveRange' || type === 'model:liveRange' ||
         // From super.is(). This is highly utilised method and cannot call super. See ckeditor/ckeditor5#6529.
         type == 'range' || type === 'model:range';
 };
-// Binds this `LiveRange` to the {@link module:engine/model/document~Document document}
-// that owns this range's {@link module:engine/model/range~Range#root root}.
-//
-// @private
+/**
+ * Binds this `LiveRange` to the {@link module:engine/model/document~Document document}
+ * that owns this range's {@link module:engine/model/range~Range#root root}.
+ */
 function bindWithDocument() {
     this.listenTo(this.root.document.model, 'applyOperation', (event, args) => {
         const operation = args[0];
@@ -86,10 +66,9 @@ function bindWithDocument() {
         transform.call(this, operation);
     }, { priority: 'low' });
 }
-// Updates this range accordingly to the updates applied to the model. Bases on change events.
-//
-// @private
-// @param {module:engine/model/operation/operation~Operation} operation Executed operation.
+/**
+ * Updates this range accordingly to the updates applied to the model. Bases on change events.
+ */
 function transform(operation) {
     // Transform the range by the operation. Join the result ranges if needed.
     const ranges = this.getTransformedByOperation(operation);
@@ -120,12 +99,9 @@ function transform(operation) {
         this.fire('change:content', this.toRange(), { deletionPosition });
     }
 }
-// Checks whether given operation changes something inside the range (even if it does not change boundaries).
-//
-// @private
-// @param {module:engine/model/range~Range} range Range to check.
-// @param {module:engine/model/operation/operation~Operation} operation Executed operation.
-// @returns {Boolean}
+/**
+ * Checks whether given operation changes something inside the range (even if it does not change boundaries).
+ */
 function doesOperationChangeRangeContent(range, operation) {
     switch (operation.type) {
         case 'insert':

package/src/model/markercollection.js

@@ -1,15 +1,13 @@
 /**
- * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @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 new-cap */
 /**
  * @module engine/model/markercollection
  */
 import TypeCheckable from './typecheckable';
 import LiveRange from './liverange';
-import EmitterMixin, { Emitter } from '@ckeditor/ckeditor5-utils/src/emittermixin';
-import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
+import { CKEditorError, EmitterMixin } from '@ckeditor/ckeditor5-utils';
 /**
  * The collection of all {@link module:engine/model/markercollection~Marker markers} attached to the document.
  * It lets you {@link module:engine/model/markercollection~MarkerCollection#get get} markers or track them using
@@ -24,17 +22,11 @@ import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
  *
  * @see module:engine/model/markercollection~Marker
  */
-export default class MarkerCollection extends Emitter {
-    /**
-     * Creates a markers collection.
-     */
+export default class MarkerCollection extends EmitterMixin() {
     constructor() {
-        super();
+        super(...arguments);
         /**
          * Stores {@link ~Marker markers} added to the collection.
-         *
-         * @private
-         * @member {Map} #_markers
          */
         this._markers = new Map();
     }
@@ -42,8 +34,6 @@ export default class MarkerCollection extends Emitter {
      * Iterable interface.
      *
      * Iterates over all {@link ~Marker markers} added to the collection.
-     *
-     * @returns {Iterator}
      */
     [Symbol.iterator]() {
         return this._markers.values();
@@ -51,8 +41,8 @@ export default class MarkerCollection extends Emitter {
     /**
      * Checks if given {@link ~Marker marker} or marker name is in the collection.
      *
-     * @param {String|module:engine/model/markercollection~Marker} markerOrName Name of marker or marker instance to check.
-     * @returns {Boolean} `true` if marker is in the collection, `false` otherwise.
+     * @param markerOrName Name of marker or marker instance to check.
+     * @returns `true` if marker is in the collection, `false` otherwise.
      */
     has(markerOrName) {
         const markerName = markerOrName instanceof Marker ? markerOrName.name : markerOrName;
@@ -61,8 +51,8 @@ export default class MarkerCollection extends Emitter {
     /**
      * Returns {@link ~Marker marker} with given `markerName`.
      *
-     * @param {String} markerName Name of marker to get.
-     * @returns {module:engine/model/markercollection~Marker|null} Marker with given name or `null` if such marker was
+     * @param markerName Name of marker to get.
+     * @returns Marker with given name or `null` if such marker was
      * not added to the collection.
      */
     get(markerName) {
@@ -78,14 +68,13 @@ export default class MarkerCollection extends Emitter {
      * flag has changed.
      *
      * @internal
-     * @protected
-     * @fires module:engine/model/markercollection~MarkerCollection#event:update
-     * @param {String|module:engine/model/markercollection~Marker} markerOrName Name of marker to set or marker instance to update.
-     * @param {module:engine/model/range~Range} range Marker range.
-     * @param {Boolean} [managedUsingOperations=false] Specifies whether the marker is managed using operations.
-     * @param {Boolean} [affectsData=false] Specifies whether the marker affects the data produced by the data pipeline
+     * @fires update
+     * @param markerOrName Name of marker to set or marker instance to update.
+     * @param range Marker range.
+     * @param managedUsingOperations Specifies whether the marker is managed using operations.
+     * @param affectsData Specifies whether the marker affects the data produced by the data pipeline
      * (is persisted in the editor's data).
-     * @returns {module:engine/model/markercollection~Marker} `Marker` instance which was added or updated.
+     * @returns `Marker` instance which was added or updated.
      */
     _set(markerOrName, range, managedUsingOperations = false, affectsData = false) {
         const markerName = markerOrName instanceof Marker ? markerOrName.name : markerOrName;
@@ -129,10 +118,9 @@ export default class MarkerCollection extends Emitter {
      * Removes given {@link ~Marker marker} or a marker with given name from the `MarkerCollection`.
      *
      * @internal
-     * @protected
-     * @fires module:engine/model/markercollection~MarkerCollection#event:update
-     * @param {String|module:engine/model/markercollection~Marker} markerOrName Marker or name of a marker to remove.
-     * @returns {Boolean} `true` if marker was found and removed, `false` otherwise.
+     * @fires update
+     * @param markerOrName Marker or name of a marker to remove.
+     * @returns `true` if marker was found and removed, `false` otherwise.
      */
     _remove(markerOrName) {
         const markerName = markerOrName instanceof Marker ? markerOrName.name : markerOrName;
@@ -151,9 +139,8 @@ export default class MarkerCollection extends Emitter {
      * conversion} for the marker.
      *
      * @internal
-     * @protected
-     * @fires module:engine/model/markercollection~MarkerCollection#event:update
-     * @param {String|module:engine/model/markercollection~Marker} markerOrName Marker or name of a marker to refresh.
+     * @fires update
+     * @param markerOrName Marker or name of a marker to refresh.
      */
     _refresh(markerOrName) {
         const markerName = markerOrName instanceof Marker ? markerOrName.name : markerOrName;
@@ -171,9 +158,6 @@ export default class MarkerCollection extends Emitter {
     }
     /**
      * Returns iterator that iterates over all markers, which ranges contain given {@link module:engine/model/position~Position position}.
-     *
-     * @param {module:engine/model/position~Position} position
-     * @returns {Iterable.<module:engine/model/markercollection~Marker>}
      */
     *getMarkersAtPosition(position) {
         for (const marker of this) {
@@ -184,9 +168,6 @@ export default class MarkerCollection extends Emitter {
     }
     /**
      * Returns iterator that iterates over all markers, which intersects with given {@link module:engine/model/range~Range range}.
-     *
-     * @param {module:engine/model/range~Range} range
-     * @returns {Iterable.<module:engine/model/markercollection~Marker>}
      */
     *getMarkersIntersectingRange(range) {
         for (const marker of this) {
@@ -208,15 +189,14 @@ export default class MarkerCollection extends Emitter {
     /**
      * Iterates over all markers that starts with given `prefix`.
      *
-     *		const markerFooA = markersCollection.set( 'foo:a', rangeFooA );
-     *		const markerFooB = markersCollection.set( 'foo:b', rangeFooB );
-     *		const markerBarA = markersCollection.set( 'bar:a', rangeBarA );
-     *		const markerFooBarA = markersCollection.set( 'foobar:a', rangeFooBarA );
-     *		Array.from( markersCollection.getMarkersGroup( 'foo' ) ); // [ markerFooA, markerFooB ]
-     *		Array.from( markersCollection.getMarkersGroup( 'a' ) ); // []
-     *
-     * @param prefix
-     * @returns {Iterable.<module:engine/model/markercollection~Marker>}
+     * ```ts
+     * const markerFooA = markersCollection.set( 'foo:a', rangeFooA );
+     * const markerFooB = markersCollection.set( 'foo:b', rangeFooB );
+     * const markerBarA = markersCollection.set( 'bar:a', rangeBarA );
+     * const markerFooBarA = markersCollection.set( 'foobar:a', rangeFooBarA );
+     * Array.from( markersCollection.getMarkersGroup( 'foo' ) ); // [ markerFooA, markerFooB ]
+     * Array.from( markersCollection.getMarkersGroup( 'a' ) ); // []
+     * ```
      */
     *getMarkersGroup(prefix) {
         for (const marker of this._markers.values()) {
@@ -227,9 +207,6 @@ export default class MarkerCollection extends Emitter {
     }
     /**
      * Destroys the marker.
-     *
-     * @private
-     * @param {module:engine/model/markercollection~Marker} marker Marker to destroy.
      */
     _destroyMarker(marker) {
         marker.stopListening();
@@ -279,13 +256,15 @@ export default class MarkerCollection extends Emitter {
  * Both type of them should be added / updated by {@link module:engine/model/writer~Writer#addMarker}
  * and removed by {@link module:engine/model/writer~Writer#removeMarker} methods.
  *
- *		model.change( ( writer ) => {
- * 			const marker = writer.addMarker( name, { range, usingOperation: true } );
+ * ```ts
+ * model.change( ( writer ) => {
+ * 	const marker = writer.addMarker( name, { range, usingOperation: true } );
  *
- * 			// ...
+ * 	// ...
  *
- * 			writer.removeMarker( marker );
- *		} );
+ * 	writer.removeMarker( marker );
+ * } );
+ * ```
  *
  * See {@link module:engine/model/writer~Writer} to find more examples.
  *
@@ -307,50 +286,22 @@ class Marker extends EmitterMixin(TypeCheckable) {
     /**
      * Creates a marker instance.
      *
-     * @param {String} name Marker name.
-     * @param {module:engine/model/liverange~LiveRange} liveRange Range marked by the marker.
-     * @param {Boolean} managedUsingOperations Specifies whether the marker is managed using operations.
-     * @param {Boolean} affectsData Specifies whether the marker affects the data produced by the data pipeline
-     * (is persisted in the editor's data).
+     * @param name Marker name.
+     * @param liveRange Range marked by the marker.
+     * @param managedUsingOperations Specifies whether the marker is managed using operations.
+     * @param affectsData Specifies whether the marker affects the data produced by the data pipeline (is persisted in the editor's data).
      */
     constructor(name, liveRange, managedUsingOperations, affectsData) {
         super();
-        /**
-         * Marker's name.
-         *
-         * @readonly
-         * @type {String}
-         */
         this.name = name;
-        /**
-         * Range marked by the marker.
-         *
-         * @protected
-         * @member {module:engine/model/liverange~LiveRange}
-         */
         this._liveRange = this._attachLiveRange(liveRange);
-        /**
-         * Flag indicates if the marker is managed using operations or not.
-         *
-         * @private
-         * @member {Boolean}
-         */
         this._managedUsingOperations = managedUsingOperations;
-        /**
-         * Specifies whether the marker affects the data produced by the data pipeline
-         * (is persisted in the editor's data).
-         *
-         * @private
-         * @member {Boolean}
-         */
         this._affectsData = affectsData;
     }
     /**
      * A value indicating if the marker is managed using operations.
      * See {@link ~Marker marker class description} to learn more about marker types.
      * See {@link module:engine/model/writer~Writer#addMarker}.
-     *
-     * @returns {Boolean}
      */
     get managedUsingOperations() {
         if (!this._liveRange) {
@@ -360,8 +311,6 @@ class Marker extends EmitterMixin(TypeCheckable) {
     }
     /**
      * A value indicating if the marker changes the data.
-     *
-     * @returns {Boolean}
      */
     get affectsData() {
         if (!this._liveRange) {
@@ -371,8 +320,6 @@ class Marker extends EmitterMixin(TypeCheckable) {
     }
     /**
      * Returns the marker data (properties defining the marker).
-     *
-     * @returns {module:engine/model/markercollection~MarkerData}
      */
     getData() {
         return {
@@ -383,8 +330,6 @@ class Marker extends EmitterMixin(TypeCheckable) {
     }
     /**
      * Returns current marker start position.
-     *
-     * @returns {module:engine/model/position~Position}
      */
     getStart() {
         if (!this._liveRange) {
@@ -394,8 +339,6 @@ class Marker extends EmitterMixin(TypeCheckable) {
     }
     /**
      * Returns current marker end position.
-     *
-     * @returns {module:engine/model/position~Position}
      */
     getEnd() {
         if (!this._liveRange) {
@@ -412,8 +355,6 @@ class Marker extends EmitterMixin(TypeCheckable) {
      * and get `Marker` instance from {@link module:engine/model/markercollection~MarkerCollection MarkerCollection} every
      * time there is a need to read marker properties. This will guarantee that the marker has not been removed and
      * that it's data is up-to-date.
-     *
-     * @returns {module:engine/model/range~Range}
      */
     getRange() {
         if (!this._liveRange) {
@@ -425,9 +366,8 @@ class Marker extends EmitterMixin(TypeCheckable) {
      * Binds new live range to the marker and detach the old one if is attached.
      *
      * @internal
-     * @protected
-     * @param {module:engine/model/liverange~LiveRange} liveRange Live range to attach
-     * @returns {module:engine/model/liverange~LiveRange} Attached live range.
+     * @param liveRange Live range to attach
+     * @returns Attached live range.
      */
     _attachLiveRange(liveRange) {
         if (this._liveRange) {
@@ -443,7 +383,6 @@ class Marker extends EmitterMixin(TypeCheckable) {
      * Unbinds and destroys currently attached live range.
      *
      * @internal
-     * @protected
      */
     _detachLiveRange() {
         this._liveRange.stopDelegating('change:range', this);
@@ -452,20 +391,8 @@ class Marker extends EmitterMixin(TypeCheckable) {
         this._liveRange = null;
     }
 }
-/**
- * Checks whether this object is of the given.
- *
- *		marker.is( 'marker' ); // -> true
- *		marker.is( 'model:marker' ); // -> true
- *
- *		marker.is( 'view:element' ); // -> false
- *		marker.is( 'documentSelection' ); // -> false
- *
- * {@link module:engine/model/node~Node#is Check the entire list of model objects} which implement the `is()` method.
- *
- * @param {String} type
- * @returns {Boolean}
- */
+// The magic of type inference using `is` method is centralized in `TypeCheckable` class.
+// Proper overload would interfere with that.
 Marker.prototype.is = function (type) {
     return type === 'marker' || type === 'model:marker';
 };