@ckeditor/ckeditor5-ui 35.2.0 → 35.3.0

package/src/viewcollection.js

@@ -2,14 +2,11 @@
  * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
-
 /**
  * @module ui/viewcollection
  */
-
 import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
 import Collection from '@ckeditor/ckeditor5-utils/src/collection';
-
 /**
  * Collects {@link module:ui/view~View} instances.
  *
@@ -48,185 +45,157 @@ import Collection from '@ckeditor/ckeditor5-utils/src/collection';
  * @mixes module:utils/observablemixin~ObservableMixin
  */
 export default class ViewCollection extends Collection {
-	/**
-	 * Creates a new instance of the {@link module:ui/viewcollection~ViewCollection}.
-	 *
-	 * @param {Iterable.<module:ui/view~View>} [initialItems] The initial items of the collection.
-	 */
-	constructor( initialItems = [] ) {
-		super( initialItems, {
-			// An #id Number attribute should be legal and not break the `ViewCollection` instance.
-			// https://github.com/ckeditor/ckeditor5-ui/issues/93
-			idProperty: 'viewUid'
-		} );
-
-		// Handle {@link module:ui/view~View#element} in DOM when a new view is added to the collection.
-		this.on( 'add', ( evt, view, index ) => {
-			this._renderViewIntoCollectionParent( view, index );
-		} );
-
-		// Handle {@link module:ui/view~View#element} in DOM when a view is removed from the collection.
-		this.on( 'remove', ( evt, view ) => {
-			if ( view.element && this._parentElement ) {
-				view.element.remove();
-			}
-		} );
-
-		/**
-		 * A parent element within which child views are rendered and managed in DOM.
-		 *
-		 * @protected
-		 * @member {HTMLElement}
-		 */
-		this._parentElement = null;
-	}
-
-	/**
-	 * Destroys the view collection along with child views.
-	 * See the view {@link module:ui/view~View#destroy} method.
-	 */
-	destroy() {
-		this.map( view => view.destroy() );
-	}
-
-	/**
-	 * Sets the parent HTML element of this collection. When parent is set, {@link #add adding} and
-	 * {@link #remove removing} views in the collection synchronizes their
-	 * {@link module:ui/view~View#element elements} in the parent element.
-	 *
-	 * @param {HTMLElement} element A new parent element.
-	 */
-	setParent( elementOrDocFragment ) {
-		this._parentElement = elementOrDocFragment;
-
-		// Take care of the initial collection items passed to the constructor.
-		for ( const view of this ) {
-			this._renderViewIntoCollectionParent( view );
-		}
-	}
-
-	/**
-	 * Delegates selected events coming from within views in the collection to any
-	 * {@link module:utils/emittermixin~Emitter}.
-	 *
-	 * For the following views and collection:
-	 *
-	 *		const viewA = new View();
-	 *		const viewB = new View();
-	 *		const viewC = new View();
-	 *
-	 *		const views = parentView.createCollection();
-	 *
-	 *		views.delegate( 'eventX' ).to( viewB );
-	 *		views.delegate( 'eventX', 'eventY' ).to( viewC );
-	 *
-	 *		views.add( viewA );
-	 *
-	 * the `eventX` is delegated (fired by) `viewB` and `viewC` along with `customData`:
-	 *
-	 *		viewA.fire( 'eventX', customData );
-	 *
-	 * and `eventY` is delegated (fired by) `viewC` along with `customData`:
-	 *
-	 *		viewA.fire( 'eventY', customData );
-	 *
-	 * See {@link module:utils/emittermixin~Emitter#delegate}.
-	 *
-	 * @param {...String} events {@link module:ui/view~View} event names to be delegated to another
-	 * {@link module:utils/emittermixin~Emitter}.
-	 * @returns {Object}
-	 * @returns {Function} return.to A function which accepts the destination of
-	 * {@link module:utils/emittermixin~Emitter#delegate delegated} events.
-	 */
-	delegate( ...events ) {
-		if ( !events.length || !isStringArray( events ) ) {
-			/**
-			 * All event names must be strings.
-			 *
-			 * @error ui-viewcollection-delegate-wrong-events
-			 */
-			throw new CKEditorError(
-				'ui-viewcollection-delegate-wrong-events',
-				this
-			);
-		}
-
-		return {
-			/**
-			 * Selects destination for {@link module:utils/emittermixin~Emitter#delegate} events.
-			 *
-			 * @memberOf module:ui/viewcollection~ViewCollection#delegate
-			 * @function module:ui/viewcollection~ViewCollection#delegate.to
-			 * @param {module:utils/emittermixin~Emitter} dest An `Emitter` instance which is
-			 * the destination for delegated events.
-			 */
-			to: dest => {
-				// Activate delegating on existing views in this collection.
-				for ( const view of this ) {
-					for ( const evtName of events ) {
-						view.delegate( evtName ).to( dest );
-					}
-				}
-
-				// Activate delegating on future views in this collection.
-				this.on( 'add', ( evt, view ) => {
-					for ( const evtName of events ) {
-						view.delegate( evtName ).to( dest );
-					}
-				} );
-
-				// Deactivate delegating when view is removed from this collection.
-				this.on( 'remove', ( evt, view ) => {
-					for ( const evtName of events ) {
-						view.stopDelegating( evtName, dest );
-					}
-				} );
-			}
-		};
-	}
-
-	/**
-	 * This method {@link module:ui/view~View#render renders} a new view added to the collection.
-	 *
-	 * If the {@link #_parentElement parent element} of the collection is set, this method also adds
-	 * the view's {@link module:ui/view~View#element} as a child of the parent in DOM at a specified index.
-	 *
-	 * **Note**: If index is not specified, the view's element is pushed as the last child
-	 * of the parent element.
-	 *
-	 * @private
-	 * @param {module:ui/view~View} view A new view added to the collection.
-	 * @param {Number} [index] An index the view holds in the collection. When not specified,
-	 * the view is added at the end.
-	 */
-	_renderViewIntoCollectionParent( view, index ) {
-		if ( !view.isRendered ) {
-			view.render();
-		}
-
-		if ( view.element && this._parentElement ) {
-			this._parentElement.insertBefore( view.element, this._parentElement.children[ index ] );
-		}
-	}
-
-	/**
-	 * Removes a child view from the collection. If the {@link #setParent parent element} of the
-	 * collection has been set, the {@link module:ui/view~View#element element} of the view is also removed
-	 * in DOM, reflecting the order of the collection.
-	 *
-	 * See the {@link #add} method.
-	 *
-	 * @method #remove
-	 * @param {module:ui/view~View|Number|String} subject The view to remove, its id or index in the collection.
-	 * @returns {Object} The removed view.
-	 */
+    /**
+     * Creates a new instance of the {@link module:ui/viewcollection~ViewCollection}.
+     *
+     * @param {Iterable.<module:ui/view~View>} [initialItems] The initial items of the collection.
+     */
+    constructor(initialItems = []) {
+        super(initialItems, {
+            // An #id Number attribute should be legal and not break the `ViewCollection` instance.
+            // https://github.com/ckeditor/ckeditor5-ui/issues/93
+            idProperty: 'viewUid'
+        });
+        // Handle {@link module:ui/view~View#element} in DOM when a new view is added to the collection.
+        this.on('add', (evt, view, index) => {
+            this._renderViewIntoCollectionParent(view, index);
+        });
+        // Handle {@link module:ui/view~View#element} in DOM when a view is removed from the collection.
+        this.on('remove', (evt, view) => {
+            if (view.element && this._parentElement) {
+                view.element.remove();
+            }
+        });
+        /**
+         * A parent element within which child views are rendered and managed in DOM.
+         *
+         * @protected
+         * @member {HTMLElement}
+         */
+        this._parentElement = null;
+    }
+    /**
+     * Destroys the view collection along with child views.
+     * See the view {@link module:ui/view~View#destroy} method.
+     */
+    destroy() {
+        this.map(view => view.destroy());
+    }
+    /**
+     * Sets the parent HTML element of this collection. When parent is set, {@link #add adding} and
+     * {@link #remove removing} views in the collection synchronizes their
+     * {@link module:ui/view~View#element elements} in the parent element.
+     *
+     * @param {HTMLElement} element A new parent element.
+     */
+    setParent(elementOrDocFragment) {
+        this._parentElement = elementOrDocFragment;
+        // Take care of the initial collection items passed to the constructor.
+        for (const view of this) {
+            this._renderViewIntoCollectionParent(view);
+        }
+    }
+    /**
+     * Delegates selected events coming from within views in the collection to any
+     * {@link module:utils/emittermixin~Emitter}.
+     *
+     * For the following views and collection:
+     *
+     *		const viewA = new View();
+     *		const viewB = new View();
+     *		const viewC = new View();
+     *
+     *		const views = parentView.createCollection();
+     *
+     *		views.delegate( 'eventX' ).to( viewB );
+     *		views.delegate( 'eventX', 'eventY' ).to( viewC );
+     *
+     *		views.add( viewA );
+     *
+     * the `eventX` is delegated (fired by) `viewB` and `viewC` along with `customData`:
+     *
+     *		viewA.fire( 'eventX', customData );
+     *
+     * and `eventY` is delegated (fired by) `viewC` along with `customData`:
+     *
+     *		viewA.fire( 'eventY', customData );
+     *
+     * See {@link module:utils/emittermixin~Emitter#delegate}.
+     *
+     * @param {...String} events {@link module:ui/view~View} event names to be delegated to another
+     * {@link module:utils/emittermixin~Emitter}.
+     * @returns {Object}
+     * @returns {Function} return.to A function which accepts the destination of
+     * {@link module:utils/emittermixin~Emitter#delegate delegated} events.
+     */
+    delegate(...events) {
+        if (!events.length || !isStringArray(events)) {
+            /**
+             * All event names must be strings.
+             *
+             * @error ui-viewcollection-delegate-wrong-events
+             */
+            throw new CKEditorError('ui-viewcollection-delegate-wrong-events', this);
+        }
+        return {
+            /**
+             * Selects destination for {@link module:utils/emittermixin~Emitter#delegate} events.
+             *
+             * @memberOf module:ui/viewcollection~ViewCollection#delegate
+             * @function module:ui/viewcollection~ViewCollection#delegate.to
+             * @param {module:utils/emittermixin~Emitter} dest An `Emitter` instance which is
+             * the destination for delegated events.
+             */
+            to: dest => {
+                // Activate delegating on existing views in this collection.
+                for (const view of this) {
+                    for (const evtName of events) {
+                        view.delegate(evtName).to(dest);
+                    }
+                }
+                // Activate delegating on future views in this collection.
+                this.on('add', (evt, view) => {
+                    for (const evtName of events) {
+                        view.delegate(evtName).to(dest);
+                    }
+                });
+                // Deactivate delegating when view is removed from this collection.
+                this.on('remove', (evt, view) => {
+                    for (const evtName of events) {
+                        view.stopDelegating(evtName, dest);
+                    }
+                });
+            }
+        };
+    }
+    /**
+     * This method {@link module:ui/view~View#render renders} a new view added to the collection.
+     *
+     * If the {@link #_parentElement parent element} of the collection is set, this method also adds
+     * the view's {@link module:ui/view~View#element} as a child of the parent in DOM at a specified index.
+     *
+     * **Note**: If index is not specified, the view's element is pushed as the last child
+     * of the parent element.
+     *
+     * @private
+     * @param {module:ui/view~View} view A new view added to the collection.
+     * @param {Number} [index] An index the view holds in the collection. When not specified,
+     * the view is added at the end.
+     */
+    _renderViewIntoCollectionParent(view, index) {
+        if (!view.isRendered) {
+            view.render();
+        }
+        if (view.element && this._parentElement) {
+            this._parentElement.insertBefore(view.element, this._parentElement.children[index]);
+        }
+    }
 }
-
 // Check if all entries of the array are of `String` type.
 //
 // @private
 // @param {Array} arr An array to be checked.
 // @returns {Boolean}
-function isStringArray( arr ) {
-	return arr.every( a => typeof a == 'string' );
+function isStringArray(arr) {
+    return arr.every(a => typeof a == 'string');
 }

package/src/button/button.jsdoc

@@ -1,165 +0,0 @@
-/**
- * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
- */
-
-/**
- * @module ui/button/button
- */
-
-/**
- * The button interface. Implemented by, among others, {@link module:ui/button/buttonview~ButtonView},
- * {@link module:ui/dropdown/button/splitbuttonview~SplitButtonView} and
- * {@link module:ui/dropdown/button/dropdownbuttonview~DropdownButtonView}.
- *
- * @interface module:ui/button/button~Button
- */
-
-/**
- * The label of the button view visible to the user when {@link #withText} is `true`.
- * It can also be used to create a {@link #tooltip}.
- *
- * @observable
- * @member {String} #label
- */
-
-/**
- * (Optional) The keystroke associated with the button, i.e. <kbd>CTRL+B</kbd>,
- * in the string format compatible with {@link module:utils/keyboard}.
- *
- * **Note**: Use {@link module:ui/button/button~Button#withKeystroke} if you want to display
- * the keystroke information next to the {@link module:ui/button/button~Button#label label}.
- *
- * @observable
- * @member {Boolean} #keystroke
- */
-
-/**
- * (Optional) Tooltip of the button, i.e. displayed when hovering the button with the mouse cursor.
- *
- * * If defined as a `Boolean` (e.g. `true`), then combination of `label` and `keystroke` will be set as a tooltip.
- * * If defined as a `String`, tooltip will equal the exact text of that `String`.
- * * If defined as a `Function`, `label` and `keystroke` will be passed to that function, which is to return
- * a string with the tooltip text.
- *
- *		const view = new ButtonView( locale );
- *		view.tooltip = ( label, keystroke ) => `A tooltip for ${ label } and ${ keystroke }.`
- *
- * @observable
- * @default false
- * @member {Boolean|String|Function} #tooltip
- */
-
-/**
- * (Optional) The position of the tooltip. See {@link module:ui/tooltipmanager~TooltipManager}
- * to learn more about the tooltip system.
- *
- * **Note:** It makes sense only when the {@link #tooltip `tooltip` attribute} is defined.
- *
- * @observable
- * @default 's'
- * @member {'s'|'n'|'e'|'w'|'sw'|'se'} #tooltipPosition
- */
-
-/**
- * The HTML type of the button. Default `button`.
- *
- * @observable
- * @member {'button'|'submit'|'reset'|'menu'} #type
- */
-
-/**
- * Controls whether the button view is "on". It makes sense when a feature it represents
- * is currently active, e.g. a bold button is "on" when the selection is in the bold text.
- *
- * To disable the button, use {@link #isEnabled} instead.
- *
- * @observable
- * @default true
- * @member {Boolean} #isOn
- */
-
-/**
- * Controls whether the button view is enabled, i.e. it can be clicked and execute an action.
- *
- * To change the "on" state of the button, use {@link #isOn} instead.
- *
- * @observable
- * @default true
- * @member {Boolean} #isEnabled
- */
-
-/**
- * Controls whether the button view is visible. Visible by default, buttons are hidden
- * using a CSS class.
- *
- * @observable
- * @default true
- * @member {Boolean} #isVisible
- */
-
-/**
- * Controls whether the button view is a toggle button (two–state) for assistive technologies.
- *
- * @observable
- * @default false
- * @member {Boolean} #isToggleable
- */
-
-/**
- * (Optional) Controls whether the label of the button is hidden (e.g. an icon–only button).
- *
- * @observable
- * @default false
- * @member {Boolean} #withText
- */
-
-/**
- * (Optional) Controls whether the keystroke of the button is displayed next to its
- * {@link module:ui/button/button~Button#label label}.
- *
- * **Note**: This property requires a {@link module:ui/button/button~Button#keystroke keystroke}
- * to be defined in the first place.
- *
- * @observable
- * @default false
- * @member {Boolean} #withKeystroke
- */
-
-/**
- * (Optional) An XML {@link module:ui/icon/iconview~IconView#content content} of the icon.
- * When defined, an `iconView` should be added to the button.
- *
- * @observable
- * @member {String} #icon
- */
-
-/**
- * (Optional) Controls the `tabindex` HTML attribute of the button. By default, the button is focusable
- * but does not included in the <kbd>Tab</kbd> order.
- *
- * @observable
- * @default -1
- * @member {String} #tabindex
- */
-
-/**
- * (Optional) The additional CSS class set on the button.
- *
- * @observable
- * @member {String} #class
- */
-
-/**
- * (Optional) The value of the `style` attribute of the label.
- *
- * @observable
- * @member {String} #labelStyle
- */
-
-/**
- * Fired when the button view is clicked. It won't be fired when the button {@link #isEnabled}
- * is `false`.
- *
- * @event execute
- */

package/src/dropdown/button/dropdownbutton.jsdoc

@@ -1,22 +0,0 @@
-/**
- * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
- */
-
-/**
- * @module ui/dropdown/button/dropdownbutton
- */
-
-/**
- * The dropdown button interface.
- *
- * @interface module:ui/dropdown/button/dropdownbutton~DropdownButton
- * @extends module:ui/button/button~Button
- */
-
-/**
- * Fired when the dropdown should be opened.
- * It will not be fired when the button {@link #isEnabled is disabled}.
- *
- * @event open
- */

package/src/dropdown/dropdownpanelfocusable.jsdoc

@@ -1,27 +0,0 @@
-/**
- * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
- */
-
-/**
- * @module ui/dropdown/dropdownpanelfocusable
- */
-
-/**
- * The dropdown panel interface for focusable contents. It provides two methods for managing focus of the contents
- * of dropdown's panel.
- *
- * @interface module:ui/dropdown/dropdownpanelfocusable~DropdownPanelFocusable
- */
-
-/**
- * Focuses the view element or first item in view collection on opening dropdown's panel.
- *
- * @method #focus
- */
-
-/**
- * Focuses the view element or last item in view collection on opening dropdown's panel.
- *
- * @method #focusLast
- */