@ckeditor/ckeditor5-engine 36.0.0 → 37.0.0-alpha.0

package/src/view/view.js

@@ -32,9 +32,11 @@ import { injectQuirksHandling } from './filler';
  * all changes need to be done using the {@link module:engine/view/view~View#change} method, using
  * {@link module:engine/view/downcastwriter~DowncastWriter}:
  *
- *		view.change( writer => {
- *			writer.insert( position, writer.createText( 'foo' ) );
- *		} );
+ * ```ts
+ * view.change( writer => {
+ * 	writer.insert( position, writer.createText( 'foo' ) );
+ * } );
+ * ```
  *
  * View controller also register {@link module:engine/view/observer/observer~Observer observers} which observes changes
  * on DOM and fire events on the {@link module:engine/view/document~Document Document}.
@@ -53,113 +55,52 @@ import { injectQuirksHandling } from './filler';
  *
  * If you do not need full a DOM - view management, and only want to transform a tree of view elements to a tree of DOM
  * elements you do not need this controller. You can use the {@link module:engine/view/domconverter~DomConverter DomConverter} instead.
- *
- * @mixes module:utils/observablemixin~ObservableMixin
  */
 export default class View extends ObservableMixin() {
     /**
-     * @param {module:engine/view/stylesmap~StylesProcessor} stylesProcessor The styles processor instance.
+     * @param stylesProcessor The styles processor instance.
      */
     constructor(stylesProcessor) {
         super();
-        /**
-         * Instance of the {@link module:engine/view/document~Document} associated with this view controller.
-         *
-         * @readonly
-         * @type {module:engine/view/document~Document}
-         */
-        this.document = new Document(stylesProcessor);
-        /**
-         * Instance of the {@link module:engine/view/domconverter~DomConverter domConverter} used by
-         * {@link module:engine/view/view~View#_renderer renderer}
-         * and {@link module:engine/view/observer/observer~Observer observers}.
-         *
-         * @readonly
-         * @type {module:engine/view/domconverter~DomConverter}
-         */
-        this.domConverter = new DomConverter(this.document);
         /**
          * Roots of the DOM tree. Map on the `HTMLElement`s with roots names as keys.
-         *
-         * @readonly
-         * @type {Map.<String, HTMLElement>}
          */
         this.domRoots = new Map();
-        /**
-         * Used to prevent calling {@link #forceRender} and {@link #change} during rendering view to the DOM.
-         *
-         * @readonly
-         * @member {Boolean} #isRenderingInProgress
-         */
-        this.set('isRenderingInProgress', false);
-        /**
-         * Informs whether the DOM selection is inside any of the DOM roots managed by the view.
-         *
-         * @readonly
-         * @member {Boolean} #hasDomSelection
-         */
-        this.set('hasDomSelection', false);
-        /**
-         * Instance of the {@link module:engine/view/renderer~Renderer renderer}.
-         *
-         * @protected
-         * @type {module:engine/view/renderer~Renderer}
-         */
-        this._renderer = new Renderer(this.domConverter, this.document.selection);
-        this._renderer.bind('isFocused', 'isSelecting', 'isComposing')
-            .to(this.document, 'isFocused', 'isSelecting', 'isComposing');
         /**
          * A DOM root attributes cache. It saves the initial values of DOM root attributes before the DOM element
          * is {@link module:engine/view/view~View#attachDomRoot attached} to the view so later on, when
          * the view is destroyed ({@link module:engine/view/view~View#detachDomRoot}), they can be easily restored.
          * This way, the DOM element can go back to the (clean) state as if the editing view never used it.
-         *
-         * @private
-         * @member {WeakMap.<HTMLElement,Object>}
          */
         this._initialDomRootAttributes = new WeakMap();
         /**
          * Map of registered {@link module:engine/view/observer/observer~Observer observers}.
-         *
-         * @private
-         * @type {Map.<Function, module:engine/view/observer/observer~Observer>}
          */
         this._observers = new Map();
         /**
          * Is set to `true` when {@link #change view changes} are currently in progress.
-         *
-         * @private
-         * @type {Boolean}
          */
         this._ongoingChange = false;
         /**
          * Used to prevent calling {@link #forceRender} and {@link #change} during rendering view to the DOM.
-         *
-         * @private
-         * @type {Boolean}
          */
         this._postFixersInProgress = false;
         /**
          * Internal flag to temporary disable rendering. See the usage in the {@link #_disableRendering}.
-         *
-         * @private
-         * @type {Boolean}
          */
         this._renderingDisabled = false;
         /**
          * Internal flag that disables rendering when there are no changes since the last rendering.
          * It stores information about changed selection and changed elements from attached document roots.
-         *
-         * @private
-         * @type {Boolean}
          */
         this._hasChangedSinceTheLastRendering = false;
-        /**
-         * DowncastWriter instance used in {@link #change change method} callbacks.
-         *
-         * @private
-         * @type {module:engine/view/downcastwriter~DowncastWriter}
-         */
+        this.document = new Document(stylesProcessor);
+        this.domConverter = new DomConverter(this.document);
+        this.set('isRenderingInProgress', false);
+        this.set('hasDomSelection', false);
+        this._renderer = new Renderer(this.domConverter, this.document.selection);
+        this._renderer.bind('isFocused', 'isSelecting', 'isComposing')
+            .to(this.document, 'isFocused', 'isSelecting', 'isComposing');
         this._writer = new DowncastWriter(this.document);
         // Add default observers.
         this.addObserver(MutationObserver);
@@ -201,8 +142,8 @@ export default class View extends ObservableMixin() {
      *
      * **Note:** Use {@link #detachDomRoot `detachDomRoot()`} to revert this action.
      *
-     * @param {Element} domRoot DOM root element.
-     * @param {String} [name='main'] Name of the root.
+     * @param domRoot DOM root element.
+     * @param name Name of the root.
      */
     attachDomRoot(domRoot, name = 'main') {
         const viewRoot = this.document.getRoot(name);
@@ -261,7 +202,7 @@ export default class View extends ObservableMixin() {
      * Detaches a DOM root element from the view element and restores its attributes to the state before
      * {@link #attachDomRoot `attachDomRoot()`}.
      *
-     * @param {String} name Name of the root to detach.
+     * @param name Name of the root to detach.
      */
     detachDomRoot(name) {
         const domRoot = this.domRoots.get(name);
@@ -278,8 +219,8 @@ export default class View extends ObservableMixin() {
     /**
      * Gets DOM root element.
      *
-     * @param {String} [name='main']  Name of the root.
-     * @returns {Element} DOM root element instance.
+     * @param name  Name of the root.
+     * @returns DOM root element instance.
      */
     getDomRoot(name = 'main') {
         return this.domRoots.get(name);
@@ -293,9 +234,9 @@ export default class View extends ObservableMixin() {
      * when registered for the first time. This means that features and other components can register a single observer
      * multiple times without caring whether it has been already added or not.
      *
-     * @param {Function} Observer The constructor of an observer to add.
+     * @param ObserverConstructor The constructor of an observer to add.
      * Should create an instance inheriting from {@link module:engine/view/observer/observer~Observer}.
-     * @returns {module:engine/view/observer/observer~Observer} Added observer instance.
+     * @returns Added observer instance.
      */
     addObserver(ObserverConstructor) {
         let observer = this._observers.get(ObserverConstructor);
@@ -313,8 +254,8 @@ export default class View extends ObservableMixin() {
     /**
      * Returns observer of the given type or `undefined` if such observer has not been added yet.
      *
-     * @param {Function} Observer The constructor of an observer to get.
-     * @returns {module:engine/view/observer/observer~Observer|undefined} Observer instance or undefined.
+     * @param ObserverConstructor The constructor of an observer to get.
+     * @returns Observer instance or undefined.
      */
     getObserver(ObserverConstructor) {
         return this._observers.get(ObserverConstructor);
@@ -375,18 +316,20 @@ export default class View extends ObservableMixin() {
      * to nest calls one inside another and still performs a single rendering after all those changes are made.
      * It also returns the return value of its callback.
      *
-     *		const text = view.change( writer => {
-     *			const newText = writer.createText( 'foo' );
-     *			writer.insert( position1, newText );
+     * ```ts
+     * const text = view.change( writer => {
+     * 	const newText = writer.createText( 'foo' );
+     * 	writer.insert( position1, newText );
      *
-     *			view.change( writer => {
-     *				writer.insert( position2, writer.createText( 'bar' ) );
-     *			} );
+     * 	view.change( writer => {
+     * 		writer.insert( position2, writer.createText( 'bar' ) );
+     * 	} );
      *
-     * 			writer.remove( range );
+     * 	writer.remove( range );
      *
-     * 			return newText;
-     *		} );
+     * 	return newText;
+     * } );
+     * ```
      *
      * When the outermost change block is done and rendering to the DOM is over the
      * {@link module:engine/view/view~View#event:render `View#render`} event is fired.
@@ -394,8 +337,8 @@ export default class View extends ObservableMixin() {
      * This method throws a `applying-view-changes-on-rendering` error when
      * the change block is used after rendering to the DOM has started.
      *
-     * @param {Function} callback Callback function which may modify the view.
-     * @returns {*} Value returned by the callback.
+     * @param callback Callback function which may modify the view.
+     * @returns Value returned by the callback.
      */
     change(callback) {
         if (this.isRenderingInProgress || this._postFixersInProgress) {
@@ -477,9 +420,7 @@ export default class View extends ObservableMixin() {
      * * {@link #createPositionBefore},
      * * {@link #createPositionAfter},
      *
-     * @param {module:engine/view/item~Item|module:engine/model/position~Position} itemOrPosition
-     * @param {Number|'end'|'before'|'after'} [offset] Offset or one of the flags. Used only when
-     * first parameter is a {@link module:engine/view/item~Item view item}.
+     * @param offset Offset or one of the flags. Used only when first parameter is a {@link module:engine/view/item~Item view item}.
      */
     createPositionAt(itemOrPosition, offset) {
         return Position._createAt(itemOrPosition, offset);
@@ -487,8 +428,7 @@ export default class View extends ObservableMixin() {
     /**
      * Creates a new position after given view item.
      *
-     * @param {module:engine/view/item~Item} item View item after which the position should be located.
-     * @returns {module:engine/view/position~Position}
+     * @param item View item after which the position should be located.
      */
     createPositionAfter(item) {
         return Position._createAfter(item);
@@ -496,8 +436,7 @@ export default class View extends ObservableMixin() {
     /**
      * Creates a new position before given view item.
      *
-     * @param {module:engine/view/item~Item} item View item before which the position should be located.
-     * @returns {module:engine/view/position~Position}
+     * @param item View item before which the position should be located.
      */
     createPositionBefore(item) {
         return Position._createBefore(item);
@@ -507,18 +446,14 @@ export default class View extends ObservableMixin() {
      *
      * **Note:** This factory method creates it's own {@link module:engine/view/position~Position} instances basing on passed values.
      *
-     * @param {module:engine/view/position~Position} start Start position.
-     * @param {module:engine/view/position~Position} [end] End position. If not set, range will be collapsed at `start` position.
-     * @returns {module:engine/view/range~Range}
+     * @param start Start position.
+     * @param end End position. If not set, range will be collapsed at `start` position.
      */
-    createRange(...args) {
-        return new Range(...args);
+    createRange(start, end) {
+        return new Range(start, end);
     }
     /**
      * Creates a range that starts before given {@link module:engine/view/item~Item view item} and ends after it.
-     *
-     * @param {module:engine/view/item~Item} item
-     * @returns {module:engine/view/range~Range}
      */
     createRangeOn(item) {
         return Range._createOn(item);
@@ -527,8 +462,7 @@ export default class View extends ObservableMixin() {
      * Creates a range inside an {@link module:engine/view/element~Element element} which starts before the first child of
      * that element and ends after the last child of that element.
      *
-     * @param {module:engine/view/element~Element} element Element which is a parent for the range.
-     * @returns {module:engine/view/range~Range}
+     * @param element Element which is a parent for the range.
      */
     createRangeIn(element) {
         return Range._createIn(element);
@@ -536,44 +470,48 @@ export default class View extends ObservableMixin() {
     /**
      Creates new {@link module:engine/view/selection~Selection} instance.
      *
-     * 		// Creates empty selection without ranges.
-     *		const selection = view.createSelection();
+     * ```ts
+     * // Creates empty selection without ranges.
+     * const selection = view.createSelection();
      *
-     *		// Creates selection at the given range.
-     *		const range = view.createRange( start, end );
-     *		const selection = view.createSelection( range );
+     * // Creates selection at the given range.
+     * const range = view.createRange( start, end );
+     * const selection = view.createSelection( range );
      *
-     *		// Creates selection at the given ranges
-     * 		const ranges = [ view.createRange( start1, end2 ), view.createRange( star2, end2 ) ];
-     *		const selection = view.createSelection( ranges );
+     * // Creates selection at the given ranges
+     * const ranges = [ view.createRange( start1, end2 ), view.createRange( star2, end2 ) ];
+     * const selection = view.createSelection( ranges );
      *
-     *		// Creates selection from the other selection.
-     *		const otherSelection = view.createSelection();
-     *		const selection = view.createSelection( otherSelection );
+     * // Creates selection from the other selection.
+     * const otherSelection = view.createSelection();
+     * const selection = view.createSelection( otherSelection );
      *
-     *		// Creates selection from the document selection.
-     *		const selection = view.createSelection( editor.editing.view.document.selection );
+     * // Creates selection from the document selection.
+     * const selection = view.createSelection( editor.editing.view.document.selection );
      *
-     * 		// Creates selection at the given position.
-     *		const position = view.createPositionFromPath( root, path );
-     *		const selection = view.createSelection( position );
+     * // Creates selection at the given position.
+     * const position = view.createPositionFromPath( root, path );
+     * const selection = view.createSelection( position );
      *
-     *		// Creates collapsed selection at the position of given item and offset.
-     *		const paragraph = view.createContainerElement( 'paragraph' );
-     *		const selection = view.createSelection( paragraph, offset );
+     * // Creates collapsed selection at the position of given item and offset.
+     * const paragraph = view.createContainerElement( 'paragraph' );
+     * const selection = view.createSelection( paragraph, offset );
      *
-     *		// Creates a range inside an {@link module:engine/view/element~Element element} which starts before the
-     *		// first child of that element and ends after the last child of that element.
-     *		const selection = view.createSelection( paragraph, 'in' );
+     * // Creates a range inside an {@link module:engine/view/element~Element element} which starts before the
+     * // first child of that element and ends after the last child of that element.
+     * const selection = view.createSelection( paragraph, 'in' );
      *
-     *		// Creates a range on an {@link module:engine/view/item~Item item} which starts before the item and ends
-     *		// just after the item.
-     *		const selection = view.createSelection( paragraph, 'on' );
+     * // Creates a range on an {@link module:engine/view/item~Item item} which starts before the item and ends
+     * // just after the item.
+     * const selection = view.createSelection( paragraph, 'on' );
+     * ```
      *
      * `Selection`'s factory method allow passing additional options (`backward`, `fake` and `label`) as the last argument.
      *
-     *		// Creates backward selection.
-     *		const selection = view.createSelection( range, { backward: true } );
+     * ```ts
+     * // Creates backward selection.
+     * const selection = view.createSelection( range, { backward: true } );
+     * ```
      *
      * Fake selection does not render as browser native selection over selected elements and is hidden to the user.
      * This way, no native selection UI artifacts are displayed to the user and selection over elements can be
@@ -582,16 +520,10 @@ export default class View extends ObservableMixin() {
      * Additionally fake's selection label can be provided. It will be used to describe fake selection in DOM
      * (and be  properly handled by screen readers).
      *
-     *		// Creates fake selection with label.
-     *		const selection = view.createSelection( range, { fake: true, label: 'foo' } );
-     *
-     * @param {module:engine/view/selection~Selectable} [selectable=null]
-     * @param {Number|'before'|'end'|'after'|'on'|'in'} [placeOrOffset] Offset or place when selectable is an `Item`.
-     * @param {Object} [options]
-     * @param {Boolean} [options.backward] Sets this selection instance to be backward.
-     * @param {Boolean} [options.fake] Sets this selection instance to be marked as `fake`.
-     * @param {String} [options.label] Label for the fake selection.
-     * @returns {module:engine/view/selection~Selection}
+     * ```ts
+     * // Creates fake selection with label.
+     * const selection = view.createSelection( range, { fake: true, label: 'foo' } );
+     * ```
      */
     createSelection(...args) {
         return new Selection(...args);
@@ -600,9 +532,8 @@ export default class View extends ObservableMixin() {
      * Disables or enables rendering. If the flag is set to `true` then the rendering will be disabled.
      * If the flag is set to `false` and if there was some change in the meantime, then the rendering action will be performed.
      *
-     * @protected
      * @internal
-     * @param {Boolean} flag A flag indicates whether the rendering should be disabled.
+     * @param flag A flag indicates whether the rendering should be disabled.
      */
     _disableRendering(flag) {
         this._renderingDisabled = flag;
@@ -614,8 +545,6 @@ export default class View extends ObservableMixin() {
     /**
      * Renders all changes. In order to avoid triggering the observers (e.g. selection) all observers are disabled
      * before rendering and re-enabled after that.
-     *
-     * @private
      */
     _render() {
         this.isRenderingInProgress = true;