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

package/src/controller/datacontroller.js

@@ -30,92 +30,34 @@ import HtmlDataProcessor from '../dataprocessor/htmldataprocessor';
  * An instance of the data controller is always available in the {@link module:core/editor/editor~Editor#data `editor.data`}
  * property:
  *
- *		editor.data.get( { rootName: 'customRoot' } ); // -> '<p>Hello!</p>'
- *
- * @mixes module:utils/emittermixin~EmitterMixin
+ * ```ts
+ * editor.data.get( { rootName: 'customRoot' } ); // -> '<p>Hello!</p>'
+ * ```
  */
 export default class DataController extends EmitterMixin() {
     /**
      * Creates a data controller instance.
      *
-     * @param {module:engine/model/model~Model} model Data model.
-     * @param {module:engine/view/stylesmap~StylesProcessor} stylesProcessor The styles processor instance.
+     * @param model Data model.
+     * @param stylesProcessor The styles processor instance.
      */
     constructor(model, stylesProcessor) {
         super();
-        /**
-         * Data model.
-         *
-         * @readonly
-         * @member {module:engine/model/model~Model}
-         */
         this.model = model;
-        /**
-         * Mapper used for the conversion. It has no permanent bindings, because these are created while getting data and
-         * ae cleared directly after the data are converted. However, the mapper is defined as a class property, because
-         * it needs to be passed to the `DowncastDispatcher` as a conversion API.
-         *
-         * @readonly
-         * @member {module:engine/conversion/mapper~Mapper}
-         */
         this.mapper = new Mapper();
-        /**
-         * Downcast dispatcher used by the {@link #get get method}. Downcast converters should be attached to it.
-         *
-         * @readonly
-         * @member {module:engine/conversion/downcastdispatcher~DowncastDispatcher}
-         */
         this.downcastDispatcher = new DowncastDispatcher({
             mapper: this.mapper,
             schema: model.schema
         });
         this.downcastDispatcher.on('insert:$text', insertText(), { priority: 'lowest' });
         this.downcastDispatcher.on('insert', insertAttributesAndChildren(), { priority: 'lowest' });
-        /**
-         * Upcast dispatcher used by the {@link #set set method}. Upcast converters should be attached to it.
-         *
-         * @readonly
-         * @member {module:engine/conversion/upcastdispatcher~UpcastDispatcher}
-         */
         this.upcastDispatcher = new UpcastDispatcher({
             schema: model.schema
         });
-        /**
-         * The view document used by the data controller.
-         *
-         * @readonly
-         * @member {module:engine/view/document~Document}
-         */
         this.viewDocument = new ViewDocument(stylesProcessor);
-        /**
-         * Styles processor used during the conversion.
-         *
-         * @readonly
-         * @member {module:engine/view/stylesmap~StylesProcessor}
-         */
         this.stylesProcessor = stylesProcessor;
-        /**
-         * Data processor used specifically for HTML conversion.
-         *
-         * @readonly
-         * @member {module:engine/dataprocessor/htmldataprocessor~HtmlDataProcessor} #htmlProcessor
-         */
         this.htmlProcessor = new HtmlDataProcessor(this.viewDocument);
-        /**
-         * Data processor used during the conversion.
-         * Same instance as {@link #htmlProcessor} by default. Can be replaced at run time to handle different format, e.g. XML or Markdown.
-         *
-         * @member {module:engine/dataprocessor/dataprocessor~DataProcessor} #processor
-         */
         this.processor = this.htmlProcessor;
-        /**
-         * The view downcast writer just for data conversion purposes, i.e. to modify
-         * the {@link #viewDocument}.
-         *
-         * @private
-         * @readonly
-         * @member {module:engine/view/downcastwriter~DowncastWriter}
-         */
         this._viewWriter = new ViewDowncastWriter(this.viewDocument);
         // Define default converters for text and elements.
         //
@@ -146,23 +88,26 @@ export default class DataController extends EmitterMixin() {
      * formatted by the {@link #processor data processor}.
      *
      * @fires get
-     * @param {Object} [options] Additional configuration for the retrieved data. `DataController` provides two optional
+     * @param options Additional configuration for the retrieved data. `DataController` provides two optional
      * properties: `rootName` and `trim`. Other properties of this object are specified by various editor features.
-     * @param {String} [options.rootName='main'] Root name.
-     * @param {String} [options.trim='empty'] Whether returned data should be trimmed. This option is set to `empty` by default,
+     * @param options.rootName Root name. Default 'main'.
+     * @param options.trim Whether returned data should be trimmed. This option is set to `empty` by default,
      * which means whenever editor content is considered empty, an empty string will be returned. To turn off trimming completely
      * use `'none'`. In such cases the exact content will be returned (for example a `<p>&nbsp;</p>` for an empty editor).
-     * @returns {String} Output data.
+     * @returns Output data.
      */
     get(options = {}) {
         const { rootName = 'main', trim = 'empty' } = options;
         if (!this._checkIfRootsExists([rootName])) {
             /**
-             * Cannot get data from a non-existing root. This error is thrown when {@link #get DataController#get() method}
+             * Cannot get data from a non-existing root. This error is thrown when
+             * {@link module:engine/controller/datacontroller~DataController#get `DataController#get()` method}
              * is called with a non-existent root name. For example, if there is an editor instance with only `main` root,
-             * calling {@link #get} like:
+             * calling {@link module:engine/controller/datacontroller~DataController#get} like:
              *
-             *		data.get( { rootName: 'root2' } );
+             * ```ts
+             * data.get( { rootName: 'root2' } );
+             * ```
              *
              * will throw this error.
              *
@@ -181,10 +126,9 @@ export default class DataController extends EmitterMixin() {
      * {@link module:engine/model/documentfragment~DocumentFragment model document fragment} converted by the downcast converters
      * attached to the {@link #downcastDispatcher} and formatted by the {@link #processor data processor}.
      *
-     * @param {module:engine/model/element~Element|module:engine/model/documentfragment~DocumentFragment} modelElementOrFragment
-     * The element whose content will be stringified.
-     * @param {Object} [options] Additional configuration passed to the conversion process.
-     * @returns {String} Output data.
+     * @param modelElementOrFragment The element whose content will be stringified.
+     * @param options Additional configuration passed to the conversion process.
+     * @returns Output data.
      */
     stringify(modelElementOrFragment, options = {}) {
         // Model -> view.
@@ -199,11 +143,10 @@ export default class DataController extends EmitterMixin() {
      * {@link module:engine/view/documentfragment~DocumentFragment view document fragment}.
      *
      * @fires toView
-     * @param {module:engine/model/element~Element|module:engine/model/documentfragment~DocumentFragment} modelElementOrFragment
-     * Element or document fragment whose content will be converted.
-     * @param {Object} [options={}] Additional configuration that will be available through the
+     * @param modelElementOrFragment Element or document fragment whose content will be converted.
+     * @param options Additional configuration that will be available through the
      * {@link module:engine/conversion/downcastdispatcher~DowncastConversionApi#options} during the conversion process.
-     * @returns {module:engine/view/documentfragment~DocumentFragment} Output view DocumentFragment.
+     * @returns Output view DocumentFragment.
      */
     toView(modelElementOrFragment, options = {}) {
         const viewDocument = this.viewDocument;
@@ -230,21 +173,25 @@ export default class DataController extends EmitterMixin() {
      * converted by the {@link #upcastDispatcher view-to-model converters}.
      * Initial data can be only set to a document whose {@link module:engine/model/document~Document#version} is equal 0.
      *
-     * **Note** This method is {@link module:utils/observablemixin~ObservableMixin#decorate decorated} which is
+     * **Note** This method is {@link module:utils/observablemixin~Observable#decorate decorated} which is
      * used by e.g. collaborative editing plugin that syncs remote data on init.
      *
      * When data is passed as a string, it is initialized on the default `main` root:
      *
-     *		dataController.init( '<p>Foo</p>' ); // Initializes data on the `main` root only, as no other is specified.
+     * ```ts
+     * dataController.init( '<p>Foo</p>' ); // Initializes data on the `main` root only, as no other is specified.
+     * ```
      *
      * To initialize data on a different root or multiple roots at once, an object containing `rootName` - `data` pairs should be passed:
      *
-     *		dataController.init( { main: '<p>Foo</p>', title: '<h1>Bar</h1>' } ); // Initializes data on both the `main` and `title` roots.
+     * ```ts
+     * dataController.init( { main: '<p>Foo</p>', title: '<h1>Bar</h1>' } ); // Initializes data on both the `main` and `title` roots.
+     * ```
      *
      * @fires init
-     * @param {String|Object.<String,String>} data Input data as a string or an object containing the `rootName` - `data`
+     * @param data Input data as a string or an object containing the `rootName` - `data`
      * pairs to initialize data on multiple roots at once.
-     * @returns {Promise} Promise that is resolved after the data is set on the editor.
+     * @returns Promise that is resolved after the data is set on the editor.
      */
     init(data) {
         if (this.model.document.version) {
@@ -266,11 +213,14 @@ export default class DataController extends EmitterMixin() {
         }
         if (!this._checkIfRootsExists(Object.keys(initialData))) {
             /**
-             * Cannot init data on a non-existent root. This error is thrown when {@link #init DataController#init() method}
+             * Cannot init data on a non-existent root. This error is thrown when
+             * {@link module:engine/controller/datacontroller~DataController#init DataController#init() method}
              * is called with non-existent root name. For example, if there is an editor instance with only `main` root,
-             * calling {@link #init} like:
+             * calling {@link module:engine/controller/datacontroller~DataController#init} like:
              *
-             * 		data.init( { main: '<p>Foo</p>', root2: '<p>Bar</p>' } );
+             * ```ts
+             * data.init( { main: '<p>Foo</p>', root2: '<p>Bar</p>' } );
+             * ```
              *
              * will throw this error.
              *
@@ -297,21 +247,27 @@ export default class DataController extends EmitterMixin() {
      *
      * When data is passed as a string it is set on the default `main` root:
      *
-     *		dataController.set( '<p>Foo</p>' ); // Sets data on the `main` root, as no other is specified.
+     * ```ts
+     * dataController.set( '<p>Foo</p>' ); // Sets data on the `main` root, as no other is specified.
+     * ```
      *
      * To set data on a different root or multiple roots at once, an object containing `rootName` - `data` pairs should be passed:
      *
-     *		dataController.set( { main: '<p>Foo</p>', title: '<h1>Bar</h1>' } ); // Sets data on the `main` and `title` roots as specified.
+     * ```ts
+     * dataController.set( { main: '<p>Foo</p>', title: '<h1>Bar</h1>' } ); // Sets data on the `main` and `title` roots as specified.
+     * ```
      *
      * To set the data with a preserved undo stack and add the change to the undo stack, set `{ isUndoable: true }` as a `batchType` option.
      *
-     *		dataController.set( '<p>Foo</p>', { batchType: { isUndoable: true } } );
+     * ```ts
+     * dataController.set( '<p>Foo</p>', { batchType: { isUndoable: true } } );
+     * ```
      *
      * @fires set
-     * @param {String|Object.<String,String>} data Input data as a string or an object containing the `rootName` - `data`
+     * @param data Input data as a string or an object containing the `rootName` - `data`
      * pairs to set data on multiple roots at once.
-     * @param {Object} [options={}] Options for setting data.
-     * @param {Object} [options.batchType] The batch type that will be used to create a batch for the changes applied by this method.
+     * @param options Options for setting data.
+     * @param options.batchType The batch type that will be used to create a batch for the changes applied by this method.
      * By default, the batch will be set as {@link module:engine/model/batch~Batch#isUndoable not undoable} and the undo stack will be
      * cleared after the new data is applied (all undo steps will be removed). If the batch type `isUndoable` flag is be set to `true`,
      * the undo stack will be preserved instead and not cleared when new data is applied.
@@ -326,11 +282,14 @@ export default class DataController extends EmitterMixin() {
         }
         if (!this._checkIfRootsExists(Object.keys(newData))) {
             /**
-             * Cannot set data on a non-existent root. This error is thrown when the {@link #set DataController#set() method}
+             * Cannot set data on a non-existent root. This error is thrown when the
+             * {@link module:engine/controller/datacontroller~DataController#set DataController#set() method}
              * is called with non-existent root name. For example, if there is an editor instance with only the default `main` root,
-             * calling {@link #set} like:
+             * calling {@link module:engine/controller/datacontroller~DataController#set} like:
              *
-             * 		data.set( { main: '<p>Foo</p>', root2: '<p>Bar</p>' } );
+             * ```ts
+             * data.set( { main: '<p>Foo</p>', root2: '<p>Bar</p>' } );
+             * ```
              *
              * will throw this error.
              *
@@ -354,10 +313,10 @@ export default class DataController extends EmitterMixin() {
      * attached to the {@link #upcastDispatcher}.
      *
      * @see #set
-     * @param {String} data Data to parse.
-     * @param {module:engine/model/schema~SchemaContextDefinition} [context='$root'] Base context in which the view will
-     * be converted to the model. See: {@link module:engine/conversion/upcastdispatcher~UpcastDispatcher#convert}.
-     * @returns {module:engine/model/documentfragment~DocumentFragment} Parsed data.
+     * @param data Data to parse.
+     * @param context Base context in which the view will be converted to the model.
+     * See: {@link module:engine/conversion/upcastdispatcher~UpcastDispatcher#convert}.
+     * @returns Parsed data.
      */
     parse(data, context = '$root') {
         // data -> view
@@ -374,11 +333,10 @@ export default class DataController extends EmitterMixin() {
      * {@link module:engine/model/documentfragment~DocumentFragment#markers static markers map}.
      *
      * @fires toModel
-     * @param {module:engine/view/element~Element|module:engine/view/documentfragment~DocumentFragment} viewElementOrFragment
-     * The element or document fragment whose content will be converted.
-     * @param {module:engine/model/schema~SchemaContextDefinition} [context='$root'] Base context in which the view will
-     * be converted to the model. See: {@link module:engine/conversion/upcastdispatcher~UpcastDispatcher#convert}.
-     * @returns {module:engine/model/documentfragment~DocumentFragment} Output document fragment.
+     * @param viewElementOrFragment The element or document fragment whose content will be converted.
+     * @param context Base context in which the view will be converted to the model.
+     * See: {@link module:engine/conversion/upcastdispatcher~UpcastDispatcher#convert}.
+     * @returns Output document fragment.
      */
     toModel(viewElementOrFragment, context = '$root') {
         return this.model.change(writer => {
@@ -394,8 +352,6 @@ export default class DataController extends EmitterMixin() {
      * * border: {@link module:engine/view/styles/border~addBorderRules}
      * * margin: {@link module:engine/view/styles/margin~addMarginRules}
      * * padding: {@link module:engine/view/styles/padding~addPaddingRules}
-     *
-     * @param {Function} callback
      */
     addStyleProcessorRules(callback) {
         callback(this.stylesProcessor);
@@ -408,8 +364,7 @@ export default class DataController extends EmitterMixin() {
      * The raw data can be later accessed by the {@link module:engine/view/element~Element#getCustomProperty view element custom property}
      * `"$rawContent"`.
      *
-     * @param {module:engine/view/matcher~MatcherPattern} pattern Pattern matching all view elements whose content should
-     * be treated as a raw data.
+     * @param pattern Pattern matching all view elements whose content should be treated as a raw data.
      */
     registerRawContentMatcher(pattern) {
         // No need to register the pattern if both the `htmlProcessor` and `processor` are the same instances.
@@ -427,9 +382,8 @@ export default class DataController extends EmitterMixin() {
     /**
      * Checks whether all provided root names are actually existing editor roots.
      *
-     * @private
-     * @param {Array.<String>} rootNames Root names to check.
-     * @returns {Boolean} Whether all provided root names are existing editor roots.
+     * @param rootNames Root names to check.
+     * @returns Whether all provided root names are existing editor roots.
      */
     _checkIfRootsExists(rootNames) {
         for (const rootName of rootNames) {
@@ -440,11 +394,13 @@ export default class DataController extends EmitterMixin() {
         return true;
     }
 }
-// Helper function for downcast conversion.
-//
-// Takes a document element (element that is added to a model document) and checks which markers are inside it. If the marker is collapsed
-// at element boundary, it is considered as contained inside the element and marker range is returned. Otherwise, if the marker is
-// intersecting with the element, the intersection is returned.
+/**
+ * Helper function for downcast conversion.
+ *
+ * Takes a document element (element that is added to a model document) and checks which markers are inside it. If the marker is collapsed
+ * at element boundary, it is considered as contained inside the element and marker range is returned. Otherwise, if the marker is
+ * intersecting with the element, the intersection is returned.
+ */
 function _getMarkersRelativeToElement(element) {
     const result = [];
     const doc = element.root.document;

package/src/controller/editingcontroller.d.ts

@@ -0,0 +1,98 @@
+/**
+ * @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 View from '../view/view';
+import Mapper from '../conversion/mapper';
+import DowncastDispatcher from '../conversion/downcastdispatcher';
+import type { default as Model } from '../model/model';
+import type ModelItem from '../model/item';
+import type { Marker } from '../model/markercollection';
+import type { StylesProcessor } from '../view/stylesmap';
+declare const EditingController_base: {
+    new (): import("@ckeditor/ckeditor5-utils").Observable;
+    prototype: import("@ckeditor/ckeditor5-utils").Observable;
+};
+/**
+ * A controller for the editing pipeline. The editing pipeline controls the {@link ~EditingController#model model} rendering,
+ * including selection handling. It also creates the {@link ~EditingController#view view} which builds a
+ * browser-independent virtualization over the DOM elements. The editing controller also attaches default converters.
+ */
+export default class EditingController extends EditingController_base {
+    /**
+     * Editor model.
+     */
+    readonly model: Model;
+    /**
+     * Editing view controller.
+     */
+    readonly view: View;
+    /**
+     * A mapper that describes the model-view binding.
+     */
+    readonly mapper: Mapper;
+    /**
+     * Downcast dispatcher that converts changes from the model to the {@link #view editing view}.
+     */
+    readonly downcastDispatcher: DowncastDispatcher;
+    /**
+     * Creates an editing controller instance.
+     *
+     * @param model Editing model.
+     * @param stylesProcessor The styles processor instance.
+     */
+    constructor(model: Model, stylesProcessor: StylesProcessor);
+    /**
+     * Removes all event listeners attached to the `EditingController`. Destroys all objects created
+     * by `EditingController` that need to be destroyed.
+     */
+    destroy(): void;
+    /**
+     * Calling this method will refresh the marker by triggering the downcast conversion for it.
+     *
+     * Reconverting the marker is useful when you want to change its {@link module:engine/view/element~Element view element}
+     * without changing any marker data. For instance:
+     *
+     * ```ts
+     * let isCommentActive = false;
+     *
+     * model.conversion.markerToHighlight( {
+     * 	model: 'comment',
+     * 	view: data => {
+     * 		const classes = [ 'comment-marker' ];
+     *
+     * 		if ( isCommentActive ) {
+     * 			classes.push( 'comment-marker--active' );
+     * 		}
+     *
+     * 		return { classes };
+     * 	}
+     * } );
+     *
+     * // ...
+     *
+     * // Change the property that indicates if marker is displayed as active or not.
+     * isCommentActive = true;
+     *
+     * // Reconverting will downcast and synchronize the marker with the new isCommentActive state value.
+     * editor.editing.reconvertMarker( 'comment' );
+     * ```
+     *
+     * **Note**: If you want to reconvert a model item, use {@link #reconvertItem} instead.
+     *
+     * @param markerOrName Name of a marker to update, or a marker instance.
+     */
+    reconvertMarker(markerOrName: Marker | string): void;
+    /**
+     * Calling this method will downcast a model item on demand (by requesting a refresh in the {@link module:engine/model/differ~Differ}).
+     *
+     * You can use it if you want the view representation of a specific item updated as a response to external modifications. For instance,
+     * when the view structure depends not only on the associated model data but also on some external state.
+     *
+     * **Note**: If you want to reconvert a model marker, use {@link #reconvertMarker} instead.
+     *
+     * @param item Item to refresh.
+     */
+    reconvertItem(item: ModelItem): void;
+}
+export {};

package/src/controller/editingcontroller.js

@@ -17,45 +17,19 @@ import { convertSelectionChange } from '../conversion/upcasthelpers';
  * A controller for the editing pipeline. The editing pipeline controls the {@link ~EditingController#model model} rendering,
  * including selection handling. It also creates the {@link ~EditingController#view view} which builds a
  * browser-independent virtualization over the DOM elements. The editing controller also attaches default converters.
- *
- * @mixes module:utils/observablemixin~ObservableMixin
  */
 export default class EditingController extends ObservableMixin() {
     /**
      * Creates an editing controller instance.
      *
-     * @param {module:engine/model/model~Model} model Editing model.
-     * @param {module:engine/view/stylesmap~StylesProcessor} stylesProcessor The styles processor instance.
+     * @param model Editing model.
+     * @param stylesProcessor The styles processor instance.
      */
     constructor(model, stylesProcessor) {
         super();
-        /**
-         * Editor model.
-         *
-         * @readonly
-         * @member {module:engine/model/model~Model}
-         */
         this.model = model;
-        /**
-         * Editing view controller.
-         *
-         * @readonly
-         * @member {module:engine/view/view~View}
-         */
         this.view = new View(stylesProcessor);
-        /**
-         * A mapper that describes the model-view binding.
-         *
-         * @readonly
-         * @member {module:engine/conversion/mapper~Mapper}
-         */
         this.mapper = new Mapper();
-        /**
-         * Downcast dispatcher that converts changes from the model to the {@link #view editing view}.
-         *
-         * @readonly
-         * @member {module:engine/conversion/downcastdispatcher~DowncastDispatcher} #downcastDispatcher
-         */
         this.downcastDispatcher = new DowncastDispatcher({
             mapper: this.mapper,
             schema: model.schema
@@ -128,32 +102,34 @@ export default class EditingController extends ObservableMixin() {
      * Reconverting the marker is useful when you want to change its {@link module:engine/view/element~Element view element}
      * without changing any marker data. For instance:
      *
-     *		let isCommentActive = false;
+     * ```ts
+     * let isCommentActive = false;
      *
-     *		model.conversion.markerToHighlight( {
-     *			model: 'comment',
-     *			view: data => {
-     *				const classes = [ 'comment-marker' ];
+     * model.conversion.markerToHighlight( {
+     * 	model: 'comment',
+     * 	view: data => {
+     * 		const classes = [ 'comment-marker' ];
      *
-     *				if ( isCommentActive ) {
-     *					classes.push( 'comment-marker--active' );
-     *				}
+     * 		if ( isCommentActive ) {
+     * 			classes.push( 'comment-marker--active' );
+     * 		}
      *
-     *				return { classes };
-     *			}
-     *		} );
+     * 		return { classes };
+     * 	}
+     * } );
      *
-     *		// ...
+     * // ...
      *
-     *		// Change the property that indicates if marker is displayed as active or not.
-     *		isCommentActive = true;
+     * // Change the property that indicates if marker is displayed as active or not.
+     * isCommentActive = true;
      *
-     *		// Reconverting will downcast and synchronize the marker with the new isCommentActive state value.
-     *		editor.editing.reconvertMarker( 'comment' );
+     * // Reconverting will downcast and synchronize the marker with the new isCommentActive state value.
+     * editor.editing.reconvertMarker( 'comment' );
+     * ```
      *
      * **Note**: If you want to reconvert a model item, use {@link #reconvertItem} instead.
      *
-     * @param {String|module:engine/model/markercollection~Marker} markerOrName Name of a marker to update, or a marker instance.
+     * @param markerOrName Name of a marker to update, or a marker instance.
      */
     reconvertMarker(markerOrName) {
         const markerName = typeof markerOrName == 'string' ? markerOrName : markerOrName.name;
@@ -179,7 +155,7 @@ export default class EditingController extends ObservableMixin() {
      *
      * **Note**: If you want to reconvert a model marker, use {@link #reconvertMarker} instead.
      *
-     * @param {module:engine/model/item~Item} item Item to refresh.
+     * @param item Item to refresh.
      */
     reconvertItem(item) {
         this.model.change(() => {