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

package/src/toolbar/toolbarview.js

@@ -28,9 +28,6 @@ const NESTED_TOOLBAR_ICONS = {
 };
 /**
  * The toolbar view class.
- *
- * @extends module:ui/view~View
- * @implements module:ui/dropdown/dropdownpanelfocusable~DropdownPanelFocusable
  */
 export default class ToolbarView extends View {
     /**
@@ -38,127 +35,25 @@ export default class ToolbarView extends View {
      *
      * Also see {@link #render}.
      *
-     * @param {module:utils/locale~Locale} locale The localization services instance.
-     * @param {module:ui/toolbar/toolbarview~ToolbarOptions} [options] Configuration options of the toolbar.
+     * @param locale The localization services instance.
+     * @param options Configuration options of the toolbar.
      */
     constructor(locale, options) {
         super(locale);
         const bind = this.bindTemplate;
         const t = this.t;
-        /**
-         * A reference to the options object passed to the constructor.
-         *
-         * @readonly
-         * @member {module:ui/toolbar/toolbarview~ToolbarOptions}
-         */
         this.options = options || {};
-        /**
-         * Label used by assistive technologies to describe this toolbar element.
-         *
-         * @default 'Editor toolbar'
-         * @member {String} #ariaLabel
-         */
         this.set('ariaLabel', t('Editor toolbar'));
-        /**
-         * The maximum width of the toolbar element.
-         *
-         * **Note**: When set to a specific value (e.g. `'200px'`), the value will affect the behavior of the
-         * {@link module:ui/toolbar/toolbarview~ToolbarOptions#shouldGroupWhenFull}
-         * option by changing the number of {@link #items} that will be displayed in the toolbar at a time.
-         *
-         * @observable
-         * @default 'auto'
-         * @member {String} #maxWidth
-         */
         this.set('maxWidth', 'auto');
-        /**
-         * A collection of toolbar items (buttons, dropdowns, etc.).
-         *
-         * @readonly
-         * @member {module:ui/viewcollection~ViewCollection}
-         */
         this.items = this.createCollection();
-        /**
-         * Tracks information about the DOM focus in the toolbar.
-         *
-         * @readonly
-         * @member {module:utils/focustracker~FocusTracker}
-         */
         this.focusTracker = new FocusTracker();
-        /**
-         * An instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}
-         * to handle keyboard navigation in the toolbar.
-         *
-         * @readonly
-         * @member {module:utils/keystrokehandler~KeystrokeHandler}
-         */
         this.keystrokes = new KeystrokeHandler();
-        /**
-         * An additional CSS class added to the {@link #element}.
-         *
-         * @observable
-         * @member {String} #class
-         */
         this.set('class', undefined);
-        /**
-         * When set true, makes the toolbar look compact with {@link #element}.
-         *
-         * @observable
-         * @default false
-         * @member {String} #isCompact
-         */
         this.set('isCompact', false);
-        /**
-         * A (child) view containing {@link #items toolbar items}.
-         *
-         * @readonly
-         * @member {module:ui/toolbar/toolbarview~ItemsView}
-         */
         this.itemsView = new ItemsView(locale);
-        /**
-         * A top–level collection aggregating building blocks of the toolbar.
-         *
-         *	┌───────────────── ToolbarView ─────────────────┐
-         *	| ┌──────────────── #children ────────────────┐ |
-         *	| |   ┌──────────── #itemsView ───────────┐   | |
-         *	| |   | [ item1 ] [ item2 ] ... [ itemN ] |   | |
-         *	| |   └──────────────────────────────────-┘   | |
-         *	| └───────────────────────────────────────────┘ |
-         *	└───────────────────────────────────────────────┘
-         *
-         * By default, it contains the {@link #itemsView} but it can be extended with additional
-         * UI elements when necessary.
-         *
-         * @readonly
-         * @member {module:ui/viewcollection~ViewCollection}
-         */
         this.children = this.createCollection();
         this.children.add(this.itemsView);
-        /**
-         * A collection of {@link #items} that take part in the focus cycling
-         * (i.e. navigation using the keyboard). Usually, it contains a subset of {@link #items} with
-         * some optional UI elements that also belong to the toolbar and should be focusable
-         * by the user.
-         *
-         * @readonly
-         * @member {module:ui/viewcollection~ViewCollection}
-         */
         this.focusables = this.createCollection();
-        /**
-         * Controls the orientation of toolbar items. Only available when
-         * {@link module:ui/toolbar/toolbarview~ToolbarOptions#shouldGroupWhenFull dynamic items grouping}
-         * is **disabled**.
-         *
-         * @observable
-         * @member {Boolean} #isVertical
-         */
-        /**
-         * Helps cycling over {@link #focusables focusable items} in the toolbar.
-         *
-         * @readonly
-         * @protected
-         * @member {module:ui/focuscycler~FocusCycler}
-         */
         const isRtl = locale.uiLanguageDirection === 'rtl';
         this._focusCycler = new FocusCycler({
             focusables: this.focusables,
@@ -196,15 +91,6 @@ export default class ToolbarView extends View {
                 mousedown: preventDefault(this)
             }
         });
-        /**
-         * An instance of the active toolbar behavior that shapes its look and functionality.
-         *
-         * See {@link module:ui/toolbar/toolbarview~ToolbarBehavior} to learn more.
-         *
-         * @protected
-         * @readonly
-         * @member {module:ui/toolbar/toolbarview~ToolbarBehavior}
-         */
         this._behavior = this.options.shouldGroupWhenFull ? new DynamicGrouping(this) : new StaticLayout(this);
     }
     /**
@@ -251,9 +137,9 @@ export default class ToolbarView extends View {
      * A utility that expands the plain toolbar configuration into
      * {@link module:ui/toolbar/toolbarview~ToolbarView#items} using a given component factory.
      *
-     * @param {Array.<String>|Object} itemsOrConfig The toolbar items or the entire toolbar configuration object.
-     * @param {module:ui/componentfactory~ComponentFactory} factory A factory producing toolbar items.
-     * @param {Array.<String>} [removeItems] An array of items names to be removed from the configuration. When present, applies
+     * @param itemsOrConfig The toolbar items or the entire toolbar configuration object.
+     * @param factory A factory producing toolbar items.
+     * @param removeItems An array of items names to be removed from the configuration. When present, applies
      * to this toolbar and all nested ones as well.
      */
     fillFromConfig(itemsOrConfig, factory, removeItems) {
@@ -262,9 +148,9 @@ export default class ToolbarView extends View {
     /**
      * A utility that expands the plain toolbar configuration into a list of view items using a given component factory.
      *
-     * @param {Array.<String>|Object} itemsOrConfig The toolbar items or the entire toolbar configuration object.
-     * @param {module:ui/componentfactory~ComponentFactory} factory A factory producing toolbar items.
-     * @param {Array.<String>} [removeItems] An array of items names to be removed from the configuration. When present, applies
+     * @param itemsOrConfig The toolbar items or the entire toolbar configuration object.
+     * @param factory A factory producing toolbar items.
+     * @param removeItems An array of items names to be removed from the configuration. When present, applies
      * to this toolbar and all nested ones as well.
      */
     _buildItemsFromConfig(itemsOrConfig, factory, removeItems) {
@@ -290,11 +176,10 @@ export default class ToolbarView extends View {
      * Cleans up the {@link module:ui/toolbar/toolbarview~ToolbarView#items} of the toolbar by removing unwanted items and
      * duplicated (obsolete) separators or line breaks.
      *
-     * @private
-     * @param {Array.<String>} items The toolbar items configuration.
-     * @param {module:ui/componentfactory~ComponentFactory} factory A factory producing toolbar items.
-     * @param {Array.<String>} removeItems An array of items names to be removed from the configuration.
-     * @returns {Array.<String>}  Items after the clean-up.
+     * @param items The toolbar items configuration.
+     * @param factory A factory producing toolbar items.
+     * @param removeItems An array of items names to be removed from the configuration.
+     * @returns Items after the clean-up.
      */
     _cleanItemsConfiguration(items, factory, removeItems) {
         const filteredItems = items
@@ -315,12 +200,14 @@ export default class ToolbarView extends View {
                      * is disabled in the toolbar configuration.
                      * To do this, set the `shouldNotGroupWhenFull` option to `true` in the editor configuration:
                      *
-                     *		const config = {
-                     *			toolbar: {
-                     *				items: [ ... ],
-                     *				shouldNotGroupWhenFull: true
-                     *			}
-                     *		}
+                     * ```ts
+                     * const config = {
+                     * 	toolbar: {
+                     * 		items: [ ... ],
+                     * 		shouldNotGroupWhenFull: true
+                     * 	}
+                     * }
+                     * ```
                      *
                      * Learn more about {@link module:core/editor/editorconfig~EditorConfig#toolbar toolbar configuration}.
                      *
@@ -345,10 +232,12 @@ export default class ToolbarView extends View {
                  *
                  * You can use the following snippet to retrieve all available toolbar items:
                  *
-                 *		Array.from( editor.ui.componentFactory.names() );
+                 * ```ts
+                 * Array.from( editor.ui.componentFactory.names() );
+                 * ```
                  *
                  * @error toolbarview-item-unavailable
-                 * @param {String|Object} item The name of the component or nested toolbar definition.
+                 * @param item The name of the component or nested toolbar definition.
                  */
                 logWarning('toolbarview-item-unavailable', { item });
                 return false;
@@ -360,9 +249,7 @@ export default class ToolbarView extends View {
     /**
      * Remove leading, trailing, and duplicated separators (`-` and `|`).
      *
-     * @private
-     * @param {Array.<String>} items
-     * @returns {Array.<String>} Toolbar items after the separator and line break clean-up.
+     * @returns Toolbar items after the separator and line break clean-up.
      */
     _cleanSeparatorsAndLineBreaks(items) {
         const nonSeparatorPredicate = (item) => (item !== '-' && item !== '|');
@@ -394,18 +281,16 @@ export default class ToolbarView extends View {
     /**
      * Creates a user-defined dropdown containing a toolbar with items.
      *
-     * @private
-     * @param {Object} definition A definition of the nested toolbar dropdown.
-     * @param {String} definition.label A label of the dropdown.
-     * @param {String|Boolean} [definition.icon] An icon of the drop-down. One of 'bold', 'plus', 'text', 'importExport', 'alignLeft',
+     * @param definition A definition of the nested toolbar dropdown.
+     * @param definition.label A label of the dropdown.
+     * @param definition.icon An icon of the drop-down. One of 'bold', 'plus', 'text', 'importExport', 'alignLeft',
      * 'paragraph' or an SVG string. When `false` is passed, no icon will be used.
-     * @param {Boolean} [definition.withText=false] When set `true`, the label of the dropdown will be visible. See
+     * @param definition.withText When set `true`, the label of the dropdown will be visible. See
      * {@link module:ui/button/buttonview~ButtonView#withText} to learn more.
-     * @param {Boolean|String|Function} [definition.tooltip=true] A tooltip of the dropdown button. See
-     * {@link module:ui/button/buttonview~ButtonView#tooltip} to learn more.
-     * @param {module:ui/componentfactory~ComponentFactory} componentFactory Component factory used to create items
+     * @param definition.tooltip A tooltip of the dropdown button. See
+     * {@link module:ui/button/buttonview~ButtonView#tooltip} to learn more. Defaults to `true`.
+     * @param componentFactory Component factory used to create items
      * of the nested toolbar.
-     * @returns {module:ui/dropdown/dropdownview~DropdownView}
      */
     _createNestedToolbarDropdown(definition, componentFactory, removeItems) {
         let { label, icon, items, tooltip = true, withText = false } = definition;
@@ -423,11 +308,13 @@ export default class ToolbarView extends View {
              * Without a label, the dropdown becomes inaccessible to users relying on assistive technologies.
              * Make sure the `label` property is set in your drop-down configuration:
              *
-             *		{
-             *			label: 'A human-readable label',
-             *			icon: '...',
-             *			items: [ ... ]
-             *		},
+             * ```json
+             * {
+             * 	label: 'A human-readable label',
+             * 	icon: '...',
+             * 	items: [ ... ]
+             * },
+             * ```
              *
              * Learn more about {@link module:core/editor/editorconfig~EditorConfig#toolbar toolbar configuration}.
              *
@@ -457,9 +344,6 @@ export default class ToolbarView extends View {
 /**
  * An inner block of the {@link module:ui/toolbar/toolbarview~ToolbarView} hosting its
  * {@link module:ui/toolbar/toolbarview~ToolbarView#items}.
- *
- * @private
- * @extends module:ui/view~View
  */
 class ItemsView extends View {
     /**
@@ -467,12 +351,6 @@ class ItemsView extends View {
      */
     constructor(locale) {
         super(locale);
-        /**
-         * A collection of items (buttons, dropdowns, etc.).
-         *
-         * @readonly
-         * @member {module:ui/viewcollection~ViewCollection}
-         */
         this.children = this.createCollection();
         this.setTemplate({
             tag: 'div',
@@ -490,17 +368,13 @@ class ItemsView extends View {
  * A toolbar behavior that makes it static and unresponsive to the changes of the environment.
  * At the same time, it also makes it possible to display a toolbar with a vertical layout
  * using the {@link module:ui/toolbar/toolbarview~ToolbarView#isVertical} property.
- *
- * @private
- * @implements module:ui/toolbar/toolbarview~ToolbarBehavior
  */
 class StaticLayout {
     /**
      * Creates an instance of the {@link module:ui/toolbar/toolbarview~StaticLayout} toolbar
      * behavior.
      *
-     * @param {module:ui/toolbar/toolbarview~ToolbarView} view An instance of the toolbar that this behavior
-     * is added to.
+     * @param view An instance of the toolbar that this behavior is added to.
      */
     constructor(view) {
         const bind = view.bindTemplate;
@@ -535,110 +409,25 @@ class StaticLayout {
  * that do not fit visually into a single row of the toolbar (due to limited space).
  * Items that do not fit are aggregated in a dropdown displayed at the end of the toolbar.
  *
+ * ```
  *	┌──────────────────────────────────────── ToolbarView ──────────────────────────────────────────┐
  *	| ┌─────────────────────────────────────── #children ─────────────────────────────────────────┐ |
  *	| |   ┌─────── #itemsView ────────┐ ┌──────────────────────┐ ┌── #groupedItemsDropdown ───┐   | |
  *	| |   |       #ungroupedItems     | | ToolbarSeparatorView | |        #groupedItems       |   | |
  *	| |   └──────────────────────────-┘ └──────────────────────┘ └────────────────────────────┘   | |
- *	| |                                  \---------- only when toolbar items overflow --------/    | |
+ *	| |                                  \---------- only when toolbar items overflow -------/    | |
  *	| └───────────────────────────────────────────────────────────────────────────────────────────┘ |
  *	└───────────────────────────────────────────────────────────────────────────────────────────────┘
- *
- * @private
- * @implements module:ui/toolbar/toolbarview~ToolbarBehavior
+ * ```
  */
 class DynamicGrouping {
     /**
      * Creates an instance of the {@link module:ui/toolbar/toolbarview~DynamicGrouping} toolbar
      * behavior.
      *
-     * @param {module:ui/toolbar/toolbarview~ToolbarView} view An instance of the toolbar that this behavior
-     * is added to.
+     * @param view An instance of the toolbar that this behavior is added to.
      */
     constructor(view) {
-        /**
-         * A toolbar view this behavior belongs to.
-         *
-         * @readonly
-         * @member {module:ui/toolbar~ToolbarView}
-         */
-        this.view = view;
-        /**
-         * A collection of toolbar children.
-         *
-         * @readonly
-         * @member {module:ui/viewcollection~ViewCollection}
-         */
-        this.viewChildren = view.children;
-        /**
-         * A collection of focusable toolbar elements.
-         *
-         * @readonly
-         * @member {module:ui/viewcollection~ViewCollection}
-         */
-        this.viewFocusables = view.focusables;
-        /**
-         * A view containing toolbar items.
-         *
-         * @readonly
-         * @member {module:ui/toolbar/toolbarview~ItemsView}
-         */
-        this.viewItemsView = view.itemsView;
-        /**
-         * Toolbar focus tracker.
-         *
-         * @readonly
-         * @member {module:utils/focustracker~FocusTracker}
-         */
-        this.viewFocusTracker = view.focusTracker;
-        /**
-         * Toolbar locale.
-         *
-         * @readonly
-         * @member {module:utils/locale~Locale}
-         */
-        this.viewLocale = view.locale;
-        /**
-         * Toolbar element.
-         *
-         * @readonly
-         * @member {HTMLElement} #viewElement
-         */
-        /**
-         * A subset of toolbar {@link module:ui/toolbar/toolbarview~ToolbarView#items}.
-         * Aggregates items that fit into a single row of the toolbar and were not {@link #groupedItems grouped}
-         * into a {@link #groupedItemsDropdown dropdown}. Items of this collection are displayed in the
-         * {@link module:ui/toolbar/toolbarview~ToolbarView#itemsView}.
-         *
-         * When none of the {@link module:ui/toolbar/toolbarview~ToolbarView#items} were grouped, it
-         * matches the {@link module:ui/toolbar/toolbarview~ToolbarView#items} collection in size and order.
-         *
-         * @readonly
-         * @member {module:ui/viewcollection~ViewCollection}
-         */
-        this.ungroupedItems = view.createCollection();
-        /**
-         * A subset of toolbar {@link module:ui/toolbar/toolbarview~ToolbarView#items}.
-         * A collection of the toolbar items that do not fit into a single row of the toolbar.
-         * Grouped items are displayed in a dedicated {@link #groupedItemsDropdown dropdown}.
-         *
-         * When none of the {@link module:ui/toolbar/toolbarview~ToolbarView#items} were grouped,
-         * this collection is empty.
-         *
-         * @readonly
-         * @member {module:ui/viewcollection~ViewCollection}
-         */
-        this.groupedItems = view.createCollection();
-        /**
-         * The dropdown that aggregates {@link #groupedItems grouped items} that do not fit into a single
-         * row of the toolbar. It is displayed on demand as the last of
-         * {@link module:ui/toolbar/toolbarview~ToolbarView#children toolbar children} and offers another
-         * (nested) toolbar which displays items that would normally overflow.
-         *
-         * @readonly
-         * @member {module:ui/dropdown/dropdownview~DropdownView}
-         */
-        this.groupedItemsDropdown = this._createGroupedItemsDropdown();
         /**
          * An instance of the resize observer that helps dynamically determine the geometry of the toolbar
          * and manage items that do not fit into a single row.
@@ -646,7 +435,6 @@ class DynamicGrouping {
          * **Note:** Created in {@link #_enableGroupingOnResize}.
          *
          * @readonly
-         * @member {module:utils/dom/resizeobserver~ResizeObserver}
          */
         this.resizeObserver = null;
         /**
@@ -656,7 +444,6 @@ class DynamicGrouping {
          * the padding will change and re–using `Window.getComputedStyle()` is expensive.
          *
          * @readonly
-         * @member {Number}
          */
         this.cachedPadding = null;
         /**
@@ -664,9 +451,17 @@ class DynamicGrouping {
          * and should be executed immediately the next time the toolbar shows up.
          *
          * @readonly
-         * @member {Boolean}
          */
         this.shouldUpdateGroupingOnNextResize = false;
+        this.view = view;
+        this.viewChildren = view.children;
+        this.viewFocusables = view.focusables;
+        this.viewItemsView = view.itemsView;
+        this.viewFocusTracker = view.focusTracker;
+        this.viewLocale = view.locale;
+        this.ungroupedItems = view.createCollection();
+        this.groupedItems = view.createCollection();
+        this.groupedItemsDropdown = this._createGroupedItemsDropdown();
         // Only those items that were not grouped are visible to the user.
         view.itemsView.children.bindTo(this.ungroupedItems).using(item => item);
         // Make sure all #items visible in the main space of the toolbar are "focuscycleable".
@@ -717,8 +512,7 @@ class DynamicGrouping {
     /**
      * Enables dynamic items grouping based on the dimensions of the toolbar.
      *
-     * @param {module:ui/toolbar/toolbarview~ToolbarView} view An instance of the toolbar that this behavior
-     * is added to.
+     * @param view An instance of the toolbar that this behavior is added to.
      */
     render(view) {
         this.viewElement = view.element;
@@ -741,8 +535,6 @@ class DynamicGrouping {
      * At the same time, it will also check if there is enough space in the toolbar for the first of the
      * {@link #groupedItems} to be returned back to {@link #ungroupedItems} and still fit into a single row
      * without the toolbar wrapping.
-     *
-     * @protected
      */
     _updateGrouping() {
         // Do no grouping–related geometry analysis when the toolbar is detached from visible DOM,
@@ -796,9 +588,6 @@ class DynamicGrouping {
     /**
      * Returns `true` when {@link module:ui/toolbar/toolbarview~ToolbarView#element} children visually overflow,
      * for instance if the toolbar is narrower than its members. Returns `false` otherwise.
-     *
-     * @private
-     * @type {Boolean}
      */
     get _areItemsOverflowing() {
         // An empty toolbar cannot overflow.
@@ -833,8 +622,6 @@ class DynamicGrouping {
      * them in the dropdown if necessary. It will also observe the browser window for size changes in
      * the future and respond to them by grouping more items or reverting already grouped back, depending
      * on the visual space available.
-     *
-     * @private
      */
     _enableGroupingOnResize() {
         let previousWidth;
@@ -851,8 +638,6 @@ class DynamicGrouping {
     /**
      * Enables the grouping functionality, just like {@link #_enableGroupingOnResize} but the difference is that
      * it listens to the changes of {@link module:ui/toolbar/toolbarview~ToolbarView#maxWidth} instead.
-     *
-     * @private
      */
     _enableGroupingOnMaxWidthChange(view) {
         view.on('change:maxWidth', () => {
@@ -864,8 +649,6 @@ class DynamicGrouping {
      * to the {@link #groupedItems} collection.
      *
      * The opposite of {@link #_ungroupFirstItem}.
-     *
-     * @private
      */
     _groupLastItem() {
         if (!this.groupedItems.length) {
@@ -880,8 +663,6 @@ class DynamicGrouping {
      * to the {@link #ungroupedItems} collection.
      *
      * The opposite of {@link #_groupLastItem}.
-     *
-     * @private
      */
     _ungroupFirstItem() {
         this.ungroupedItems.add(this.groupedItems.remove(this.groupedItems.first));
@@ -894,9 +675,6 @@ class DynamicGrouping {
     /**
      * Creates the {@link #groupedItemsDropdown} that hosts the members of the {@link #groupedItems}
      * collection when there is not enough space in the toolbar to display all items in a single row.
-     *
-     * @private
-     * @returns {module:ui/dropdown/dropdownview~DropdownView}
      */
     _createGroupedItemsDropdown() {
         const locale = this.viewLocale;
@@ -924,8 +702,6 @@ class DynamicGrouping {
      *
      * See the {@link module:ui/toolbar/toolbarview~ToolbarView#focusables collection} documentation
      * to learn more about the purpose of this method.
-     *
-     * @private
      */
     _updateFocusCycleableItems() {
         this.viewFocusables.clear();
@@ -937,30 +713,3 @@ class DynamicGrouping {
         }
     }
 }
-/**
- * Creates a new toolbar behavior instance.
- *
- * The instance is created in the {@link module:ui/toolbar/toolbarview~ToolbarView#constructor} of the toolbar.
- * This is the right place to extend the {@link module:ui/toolbar/toolbarview~ToolbarView#template} of
- * the toolbar, define extra toolbar properties, etc.
- *
- * @method #constructor
- * @param {module:ui/toolbar/toolbarview~ToolbarView} view An instance of the toolbar that this behavior is added to.
- */
-/**
- * A method called after the toolbar has been {@link module:ui/toolbar/toolbarview~ToolbarView#render rendered}.
- * It can be used to, for example, customize the behavior of the toolbar when its {@link module:ui/toolbar/toolbarview~ToolbarView#element}
- * is available.
- *
- * @readonly
- * @member {Function} #render
- * @param {module:ui/toolbar/toolbarview~ToolbarView} view An instance of the toolbar being rendered.
- */
-/**
- * A method called after the toolbar has been {@link module:ui/toolbar/toolbarview~ToolbarView#destroy destroyed}.
- * It allows cleaning up after the toolbar behavior, for instance, this is the right place to detach
- * event listeners, free up references, etc.
- *
- * @readonly
- * @member {Function} #destroy
- */