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

package/src/toolbar/block/blocktoolbar.js

@@ -28,33 +28,39 @@ const { pilcrow } = icons;
  * By default, the button is attached so its right boundary is touching the
  * {@link module:engine/view/editableelement~EditableElement}:
  *
- * 		 __ |
- * 		|  ||  This is a block of content that the
- * 		 ¯¯ |  button is attached to. This is a
- * 		    |  block of content that the button is
- * 		    |  attached to.
+ * ```
+ *  __ |
+ * |  ||  This is a block of content that the
+ *  ¯¯ |  button is attached to. This is a
+ *     |  block of content that the button is
+ *     |  attached to.
+ * ```
  *
  * The position of the button can be adjusted using the CSS `transform` property:
  *
- * 		.ck-block-toolbar-button {
- * 			transform: translateX( -10px );
- * 		}
+ * ```css
+ * .ck-block-toolbar-button {
+ * 	transform: translateX( -10px );
+ * }
+ * ```
  *
- * 		 __   |
- * 		|  |  |  This is a block of content that the
- * 		 ¯¯   |  button is attached to. This is a
- * 		      |  block of content that the button is
- * 		      |  attached to.
+ * ```
+ *  __   |
+ * |  |  |  This is a block of content that the
+ *  ¯¯   |  button is attached to. This is a
+ *       |  block of content that the button is
+ *       |  attached to.
+ * ```
  *
  * **Note**: If you plan to run the editor in a right–to–left (RTL) language, keep in mind the button
  * will be attached to the **right** boundary of the editable area. In that case, make sure the
  * CSS position adjustment works properly by adding the following styles:
  *
- * 		.ck[dir="rtl"] .ck-block-toolbar-button {
- * 			transform: translateX( 10px );
- * 		}
- *
- * @extends module:core/plugin~Plugin
+ * ```css
+ * .ck[dir="rtl"] .ck-block-toolbar-button {
+ * 	transform: translateX( 10px );
+ * }
+ * ```
  */
 export default class BlockToolbar extends Plugin {
     /**
@@ -68,31 +74,6 @@ export default class BlockToolbar extends Plugin {
      */
     constructor(editor) {
         super(editor);
-        /**
-         * A cached and normalized `config.blockToolbar` object.
-         *
-         * @type {module:core/editor/editorconfig~EditorConfig#blockToolbar}
-         * @private
-         */
-        this._blockToolbarConfig = normalizeToolbarConfig(this.editor.config.get('blockToolbar'));
-        /**
-         * The toolbar view.
-         *
-         * @type {module:ui/toolbar/toolbarview~ToolbarView}
-         */
-        this.toolbarView = this._createToolbarView();
-        /**
-         * The balloon panel view, containing the {@link #toolbarView}.
-         *
-         * @type {module:ui/panel/balloon/balloonpanelview~BalloonPanelView}
-         */
-        this.panelView = this._createPanelView();
-        /**
-         * The button view that opens the {@link #toolbarView}.
-         *
-         * @type {module:ui/toolbar/block/blockbuttonview~BlockButtonView}
-         */
-        this.buttonView = this._createButtonView();
         /**
          * An instance of the resize observer that allows to respond to changes in editable's geometry
          * so the toolbar can stay within its boundaries (and group toolbar items that do not fit).
@@ -101,11 +82,12 @@ export default class BlockToolbar extends Plugin {
          * {@link module:core/editor/editorconfig~EditorConfig#blockToolbar configuration}.
          *
          * **Note:** Created in {@link #afterInit}.
-         *
-         * @protected
-         * @member {module:utils/dom/resizeobserver~ResizeObserver}
          */
         this._resizeObserver = null;
+        this._blockToolbarConfig = normalizeToolbarConfig(this.editor.config.get('blockToolbar'));
+        this.toolbarView = this._createToolbarView();
+        this.panelView = this._createPanelView();
+        this.buttonView = this._createButtonView();
         // Close the #panelView upon clicking outside of the plugin UI.
         clickOutsideHandler({
             emitter: this.panelView,
@@ -152,8 +134,6 @@ export default class BlockToolbar extends Plugin {
      * Fills the toolbar with its items based on the configuration.
      *
      * **Note:** This needs to be done after all plugins are ready.
-     *
-     * @inheritDoc
      */
     afterInit() {
         const factory = this.editor.ui.componentFactory;
@@ -188,9 +168,6 @@ export default class BlockToolbar extends Plugin {
     }
     /**
      * Creates the {@link #toolbarView}.
-     *
-     * @private
-     * @returns {module:ui/toolbar/toolbarview~ToolbarView}
      */
     _createToolbarView() {
         const t = this.editor.locale.t;
@@ -210,9 +187,6 @@ export default class BlockToolbar extends Plugin {
     }
     /**
      * Creates the {@link #panelView}.
-     *
-     * @private
-     * @returns {module:ui/panel/balloon/balloonpanelview~BalloonPanelView}
      */
     _createPanelView() {
         const editor = this.editor;
@@ -230,9 +204,6 @@ export default class BlockToolbar extends Plugin {
     }
     /**
      * Creates the {@link #buttonView}.
-     *
-     * @private
-     * @returns {module:ui/toolbar/block/blockbuttonview~BlockButtonView}
      */
     _createButtonView() {
         const editor = this.editor;
@@ -278,8 +249,6 @@ export default class BlockToolbar extends Plugin {
     /**
      * Shows or hides the button.
      * When all the conditions for displaying the button are matched, it shows the button. Hides otherwise.
-     *
-     * @private
      */
     _updateButton() {
         const editor = this.editor;
@@ -315,8 +284,6 @@ export default class BlockToolbar extends Plugin {
     }
     /**
      * Hides the button.
-     *
-     * @private
      */
     _hideButton() {
         this.buttonView.isVisible = false;
@@ -324,8 +291,6 @@ export default class BlockToolbar extends Plugin {
     /**
      * Shows the {@link #toolbarView} attached to the {@link #buttonView}.
      * If the toolbar is already visible, then it simply repositions it.
-     *
-     * @private
      */
     _showPanel() {
         // Usually, the only way to show the toolbar is by pressing the block button. It makes it impossible for
@@ -372,8 +337,7 @@ export default class BlockToolbar extends Plugin {
     /**
      * Hides the {@link #toolbarView}.
      *
-     * @private
-     * @param {Boolean} [focusEditable=false] When `true`, the editable will be focused after hiding the panel.
+     * @param focusEditable When `true`, the editable will be focused after hiding the panel.
      */
     _hidePanel(focusEditable) {
         this.panelView.isVisible = false;
@@ -384,8 +348,7 @@ export default class BlockToolbar extends Plugin {
     /**
      * Attaches the {@link #buttonView} to the target block of content.
      *
-     * @protected
-     * @param {HTMLElement} targetElement Target element.
+     * @param targetElement Target element.
      */
     _attachButtonToElement(targetElement) {
         const contentStyles = window.getComputedStyle(targetElement);
@@ -420,8 +383,7 @@ export default class BlockToolbar extends Plugin {
      * Gets the {@link #toolbarView} max-width, based on
      * editable width plus distance between farthest edge of the {@link #buttonView} and the editable.
      *
-     * @private
-     * @returns {String} maxWidth A maximum width that toolbar can have, in pixels.
+     * @returns A maximum width that toolbar can have, in pixels.
      */
     _getToolbarMaxWidth() {
         const editableElement = this.editor.ui.view.editable.element;

package/src/toolbar/normalizetoolbarconfig.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @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 type { ToolbarConfig, ToolbarConfigItem } from '@ckeditor/ckeditor5-core';
+/**
+ * @module ui/toolbar/normalizetoolbarconfig
+ */
+/**
+ * Normalizes the toolbar configuration (`config.toolbar`), which:
+ *
+ * * may be defined as an `Array`:
+ *
+ * ```
+ * toolbar: [ 'heading', 'bold', 'italic', 'link', ... ]
+ * ```
+ *
+ * * or an `Object`:
+ *
+ * ```
+ * toolbar: {
+ * 	items: [ 'heading', 'bold', 'italic', 'link', ... ],
+ * 	removeItems: [ 'bold' ],
+ * 	...
+ * }
+ * ```
+ *
+ * * or may not be defined at all (`undefined`)
+ *
+ * and returns it in the object form.
+ *
+ * @param config The value of `config.toolbar`.
+ * @returns A normalized toolbar config object.
+ */
+export default function normalizeToolbarConfig(config: ToolbarConfig | undefined): {
+    items: Array<ToolbarConfigItem>;
+    removeItems: Array<string>;
+    shouldNotGroupWhenFull?: boolean;
+};

package/src/toolbar/normalizetoolbarconfig.js

@@ -10,22 +10,26 @@
  *
  * * may be defined as an `Array`:
  *
- * 		toolbar: [ 'heading', 'bold', 'italic', 'link', ... ]
+ * ```
+ * toolbar: [ 'heading', 'bold', 'italic', 'link', ... ]
+ * ```
  *
  * * or an `Object`:
  *
- *		toolbar: {
- *			items: [ 'heading', 'bold', 'italic', 'link', ... ],
- *			removeItems: [ 'bold' ],
- *			...
- *		}
+ * ```
+ * toolbar: {
+ * 	items: [ 'heading', 'bold', 'italic', 'link', ... ],
+ * 	removeItems: [ 'bold' ],
+ * 	...
+ * }
+ * ```
  *
  * * or may not be defined at all (`undefined`)
  *
  * and returns it in the object form.
  *
- * @param {Array|Object|undefined} config The value of `config.toolbar`.
- * @returns {Object} A normalized toolbar config object.
+ * @param config The value of `config.toolbar`.
+ * @returns A normalized toolbar config object.
  */
 export default function normalizeToolbarConfig(config) {
     if (Array.isArray(config)) {

package/src/toolbar/toolbarlinebreakview.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @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
+ */
+/**
+ * @module ui/toolbar/toolbarlinebreakview
+ */
+import View from '../view';
+import type { Locale } from '@ckeditor/ckeditor5-utils';
+/**
+ * The toolbar line break view class.
+ */
+export default class ToolbarLineBreakView extends View {
+    /**
+     * @inheritDoc
+     */
+    constructor(locale?: Locale);
+}

package/src/toolbar/toolbarlinebreakview.js

@@ -8,8 +8,6 @@
 import View from '../view';
 /**
  * The toolbar line break view class.
- *
- * @extends module:ui/view~View
  */
 export default class ToolbarLineBreakView extends View {
     /**

package/src/toolbar/toolbarseparatorview.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @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
+ */
+/**
+ * @module ui/toolbar/toolbarseparatorview
+ */
+import View from '../view';
+import type { Locale } from '@ckeditor/ckeditor5-utils';
+/**
+ * The toolbar separator view class.
+ */
+export default class ToolbarSeparatorView extends View {
+    /**
+     * @inheritDoc
+     */
+    constructor(locale?: Locale);
+}

package/src/toolbar/toolbarseparatorview.js

@@ -8,8 +8,6 @@
 import View from '../view';
 /**
  * The toolbar separator view class.
- *
- * @extends module:ui/view~View
  */
 export default class ToolbarSeparatorView extends View {
     /**

package/src/toolbar/toolbarview.d.ts

@@ -0,0 +1,265 @@
+/**
+ * @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
+ */
+/**
+ * @module ui/toolbar/toolbarview
+ */
+import View from '../view';
+import type ComponentFactory from '../componentfactory';
+import type ViewCollection from '../viewcollection';
+import type DropdownPanelFocusable from '../dropdown/dropdownpanelfocusable';
+import { FocusTracker, KeystrokeHandler, type Locale } from '@ckeditor/ckeditor5-utils';
+import { type ToolbarConfig } from '@ckeditor/ckeditor5-core';
+import '../../theme/components/toolbar/toolbar.css';
+/**
+ * The toolbar view class.
+ */
+export default class ToolbarView extends View implements DropdownPanelFocusable {
+    /**
+     * A reference to the options object passed to the constructor.
+     */
+    readonly options: ToolbarOptions;
+    /**
+     * A collection of toolbar items (buttons, dropdowns, etc.).
+     */
+    readonly items: ViewCollection;
+    /**
+     * Tracks information about the DOM focus in the toolbar.
+     */
+    readonly focusTracker: FocusTracker;
+    /**
+     * An instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}
+     * to handle keyboard navigation in the toolbar.
+     */
+    readonly keystrokes: KeystrokeHandler;
+    /**
+     * A (child) view containing {@link #items toolbar items}.
+     */
+    readonly itemsView: ItemsView;
+    /**
+     * 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 children: ViewCollection;
+    /**
+     * 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 focusables: ViewCollection;
+    locale: Locale;
+    /**
+     * Label used by assistive technologies to describe this toolbar element.
+     *
+     * @observable
+     * @default 'Editor toolbar'
+     */
+    ariaLabel: string;
+    /**
+     * 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'
+     */
+    maxWidth: string;
+    /**
+     * An additional CSS class added to the {@link #element}.
+     *
+     * @observable
+     * @member {String} #class
+     */
+    class: string | undefined;
+    /**
+     * When set true, makes the toolbar look compact with {@link #element}.
+     *
+     * @observable
+     * @default false
+     */
+    isCompact: boolean;
+    /**
+     * Controls the orientation of toolbar items. Only available when
+     * {@link module:ui/toolbar/toolbarview~ToolbarOptions#shouldGroupWhenFull dynamic items grouping}
+     * is **disabled**.
+     *
+     * @observable
+     */
+    isVertical: boolean;
+    /**
+     * Helps cycling over {@link #focusables focusable items} in the toolbar.
+     */
+    private readonly _focusCycler;
+    /**
+     * An instance of the active toolbar behavior that shapes its look and functionality.
+     *
+     * See {@link module:ui/toolbar/toolbarview~ToolbarBehavior} to learn more.
+     */
+    private readonly _behavior;
+    /**
+     * Creates an instance of the {@link module:ui/toolbar/toolbarview~ToolbarView} class.
+     *
+     * Also see {@link #render}.
+     *
+     * @param locale The localization services instance.
+     * @param options Configuration options of the toolbar.
+     */
+    constructor(locale: Locale, options?: ToolbarOptions);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Focuses the first focusable in {@link #focusables}.
+     */
+    focus(): void;
+    /**
+     * Focuses the last focusable in {@link #focusables}.
+     */
+    focusLast(): void;
+    /**
+     * A utility that expands the plain toolbar configuration into
+     * {@link module:ui/toolbar/toolbarview~ToolbarView#items} using a given component factory.
+     *
+     * @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: ToolbarConfig | undefined, factory: ComponentFactory, removeItems?: Array<string>): void;
+    /**
+     * A utility that expands the plain toolbar configuration into a list of view items using a given component factory.
+     *
+     * @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.
+     */
+    private _buildItemsFromConfig;
+    /**
+     * Cleans up the {@link module:ui/toolbar/toolbarview~ToolbarView#items} of the toolbar by removing unwanted items and
+     * duplicated (obsolete) separators or line breaks.
+     *
+     * @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.
+     */
+    private _cleanItemsConfiguration;
+    /**
+     * Remove leading, trailing, and duplicated separators (`-` and `|`).
+     *
+     * @returns Toolbar items after the separator and line break clean-up.
+     */
+    private _cleanSeparatorsAndLineBreaks;
+    /**
+     * Creates a user-defined dropdown containing a toolbar with items.
+     *
+     * @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 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 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.
+     */
+    private _createNestedToolbarDropdown;
+}
+/**
+ * Fired when some toolbar {@link ~ToolbarView#items} were grouped or ungrouped as a result of some change
+ * in the toolbar geometry.
+ *
+ * **Note**: This event is always fired **once** regardless of the number of items that were be
+ * grouped or ungrouped at a time.
+ *
+ * **Note**: This event is fired only if the items grouping functionality was enabled in
+ * the first place (see {@link module:ui/toolbar/toolbarview~ToolbarOptions#shouldGroupWhenFull}).
+ *
+ * @eventName ~ToolbarView#groupedItemsUpdate
+ */
+export type ToolbarViewGroupedItemsUpdateEvent = {
+    name: 'groupedItemsUpdate';
+    args: [];
+};
+/**
+ * An inner block of the {@link module:ui/toolbar/toolbarview~ToolbarView} hosting its
+ * {@link module:ui/toolbar/toolbarview~ToolbarView#items}.
+ */
+declare class ItemsView extends View {
+    /**
+     * A collection of items (buttons, dropdowns, etc.).
+     */
+    readonly children: ViewCollection;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale?: Locale);
+}
+/**
+ * Options passed to the {@link module:ui/toolbar/toolbarview~ToolbarView#constructor} of the toolbar.
+ */
+export interface ToolbarOptions {
+    /**
+     * When set to `true`, the toolbar will automatically group {@link module:ui/toolbar/toolbarview~ToolbarView#items} that
+     * would normally wrap to the next line when there is not enough space to display them in a single row, for
+     * instance, if the parent container of the toolbar is narrow. For toolbars in absolutely positioned containers
+     * without width restrictions also the {@link module:ui/toolbar/toolbarview~ToolbarOptions#isFloating} option is required to be `true`.
+     *
+     * See also: {@link module:ui/toolbar/toolbarview~ToolbarView#maxWidth}.
+     */
+    shouldGroupWhenFull?: boolean;
+    /**
+     * This option should be enabled for toolbars in absolutely positioned containers without width restrictions
+     * to enable automatic {@link module:ui/toolbar/toolbarview~ToolbarView#items} grouping.
+     * When this option is set to `true`, the items will stop wrapping to the next line
+     * and together with {@link module:ui/toolbar/toolbarview~ToolbarOptions#shouldGroupWhenFull},
+     * this will allow grouping them when there is not enough space in a single row.
+     */
+    isFloating?: boolean;
+}
+/**
+ * A class interface defining the behavior of the {@link module:ui/toolbar/toolbarview~ToolbarView}.
+ *
+ * Toolbar behaviors extend its look and functionality and have an impact on the
+ * {@link module:ui/toolbar/toolbarview~ToolbarView#element} template or
+ * {@link module:ui/toolbar/toolbarview~ToolbarView#render rendering}. They can be enabled
+ * conditionally, e.g. depending on the configuration of the toolbar.
+ */
+export interface ToolbarBehavior {
+    /**
+     * 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.
+     *
+     * @param view An instance of the toolbar being rendered.
+     */
+    render(view: ToolbarView): void;
+    /**
+     * 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.
+     */
+    destroy(): void;
+}
+export {};