@ckeditor/ckeditor5-ui 43.0.0-alpha.6 → 43.1.0-alpha.0

package/src/dropdown/menu/dropdownmenurootlistview.d.ts

@@ -0,0 +1,140 @@
+/**
+ * @license Copyright (c) 2003-2024, 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/menu/dropdownmenurootlistview
+ */
+import DropdownMenuListItemButtonView from './dropdownmenulistitembuttonview.js';
+import DropdownMenuNestedMenuView from './dropdownmenunestedmenuview.js';
+import DropdownMenuListView from './dropdownmenulistview.js';
+import type BodyCollection from '../../editorui/bodycollection.js';
+import type { DropdownMenuDefinition } from './utils.js';
+import type { Locale, BaseEvent } from '@ckeditor/ckeditor5-utils';
+/**
+ * Creates and manages a multi-level menu UI structure, suitable to be used inside dropdown components.
+ *
+ * This class creates a menu structure based on {@link module:ui/dropdown/menu/utils~DropdownMenuDefinition declarative definition}
+ * passed in the constructor.
+ *
+ * Below is an example of a simple definition, that describes a menu with two sub-menus (Menu 1, Menu 2) and four buttons in total (Item A,
+ * Item B, Item C, Item D):
+ *
+ * ```js
+ * [
+ * 	{
+ * 		id: 'menu_1',
+ * 		menu: 'Menu 1',
+ * 		children: [
+ * 			{ id: 'menu_1_a', label: 'Item A' },
+ * 			{ id: 'menu_1_b', label: 'Item B' }
+ * 		]
+ * 	},
+ * 	{
+ * 		id: 'menu_2',
+ * 		menu: 'Menu 2',
+ * 		children: [
+ * 			{ id: 'menu_2_c', label: 'Item C' },
+ * 		]
+ * 	},
+ * 	{ id: 'item_d', label: 'Item D' }
+ * ]
+ * ```
+ *
+ * The menu is build using multiple view classes. The most important are:
+ *
+ * * {@link module:ui/dropdown/menu/dropdownmenunestedmenuview~DropdownMenuNestedMenuView `DropdownMenuNestedMenuView`} - "menu" - provides
+ * a panel with a nested menu, and a button which opens the panel,
+ * * {@link module:ui/dropdown/menu/dropdownmenulistitembuttonview~DropdownMenuListItemButtonView `DropdownMenuListItemButtonView`} -
+ * "button" or "leaf button" (as opposed to buttons provided by `DropdownMenuNestedMenuView`) - should trigger some action when pressed.
+ *
+ * Instances of these two classes are created based on the data provided in definitions. They are assigned proper IDs and labels.
+ * Other view classes build a proper DOM structure around menus and buttons.
+ *
+ * The `DropdownMenuNestedMenuView` instances provides panels, which may include further menus or buttons. These panels are added to
+ * a `BodyCollection` view, which means they are appended outside the DOM editor and UI structure.
+ *
+ * When "leaf button" is pressed, it fires `execute` event which is delegated to `DropdownMenuRootListView` as `menu:execute` event. You
+ * can listen to this event to perform an action:
+ *
+ * ```js
+ * rootListView.on( 'menu:execute', evt => {
+ * 	console.log( evt.source.id ); // E.g. will print 'menu_1_a' when 'Item A' is pressed.
+ * } );
+ * ```
+ *
+ * All menus and "leaf" buttons created from the definition can be easily accessed through {@link ~DropdownMenuRootListView#menus `menus`}
+ * and {@link ~DropdownMenuRootListView#buttons `buttons`} properties.
+ *
+ * For performance reasons, the whole menu structure is created only when `DropdownMenuRootListView` is rendered for the first time.
+ *
+ * It is recommended to use this class together with {@link module:ui/dropdown/utils~addMenuToDropdown `addMenuToDropdown()` helper}.
+ */
+export default class DropdownMenuRootListView extends DropdownMenuListView {
+    /**
+     * The CSS class to be applied to nested menu panels in this dropdown menu.
+     *
+     * It is necessary, as the panels are created in body collection, outside editor and UI structure.
+     */
+    menuPanelClass: string | undefined;
+    /**
+     * The definitions object used to create the whole menu structure.
+     */
+    private readonly _definition;
+    /**
+     * Cached array of all menus in the dropdown menu (including nested menus).
+     */
+    private _cachedMenus;
+    /**
+     * Cached array of all buttons in the dropdown menu (including buttons in nested menus).
+     */
+    private _cachedButtons;
+    /**
+     * Editor body collection into which nested menus panels will be appended.
+     */
+    private _bodyCollection;
+    /**
+     * Creates an instance of the DropdownMenuRootListView class.
+     *
+     * @param locale
+     * @param bodyCollection
+     * @param definition The definition object used to create the menu structure.
+     */
+    constructor(locale: Locale, bodyCollection: BodyCollection, definition: DropdownMenuDefinition);
+    /**
+     * Returns the array of all menus in the dropdown menu (including nested menus).
+     */
+    get menus(): Array<DropdownMenuNestedMenuView>;
+    /**
+     * Returns the array of all buttons in the dropdown menu (including buttons in nested menus).
+     *
+     * Note, that this includes only "leaf" buttons, as specified in the definition passed in constructor. Buttons created as a part of
+     * the nested menus, that open nested menus when hovered or pressed, are not included.
+     */
+    get buttons(): Array<DropdownMenuListItemButtonView>;
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * Closes all nested menus.
+     */
+    closeMenus(): void;
+    /**
+     * Recursively creates the whole view tree structure for the dropdown menu, according to the passed `definitions`.
+     *
+     * @private
+     */
+    private _createStructure;
+}
+/**
+ * Fired when one of the menu buttons is executed (through mouse click or keyboard).
+ *
+ * This event is a delegated `execute` event fired by the pressed button. The `event.source` is the button which was executed.
+ *
+ * @eventName ~DropdownMenuRootListView#menu:execute
+ */
+export interface DropdownMenuRootListViewExecuteEvent extends BaseEvent {
+    name: 'menu:execute';
+    args: [];
+}

package/src/dropdown/menu/dropdownmenurootlistview.js

@@ -0,0 +1,160 @@
+/**
+ * @license Copyright (c) 2003-2024, 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/menu/dropdownmenurootlistview
+ */
+import DropdownMenuListItemButtonView from './dropdownmenulistitembuttonview.js';
+import DropdownMenuNestedMenuView from './dropdownmenunestedmenuview.js';
+import DropdownMenuListView from './dropdownmenulistview.js';
+import DropdownMenuListItemView from './dropdownmenulistitemview.js';
+import { DropdownRootMenuBehaviors } from './dropdownmenubehaviors.js';
+/**
+ * Creates and manages a multi-level menu UI structure, suitable to be used inside dropdown components.
+ *
+ * This class creates a menu structure based on {@link module:ui/dropdown/menu/utils~DropdownMenuDefinition declarative definition}
+ * passed in the constructor.
+ *
+ * Below is an example of a simple definition, that describes a menu with two sub-menus (Menu 1, Menu 2) and four buttons in total (Item A,
+ * Item B, Item C, Item D):
+ *
+ * ```js
+ * [
+ * 	{
+ * 		id: 'menu_1',
+ * 		menu: 'Menu 1',
+ * 		children: [
+ * 			{ id: 'menu_1_a', label: 'Item A' },
+ * 			{ id: 'menu_1_b', label: 'Item B' }
+ * 		]
+ * 	},
+ * 	{
+ * 		id: 'menu_2',
+ * 		menu: 'Menu 2',
+ * 		children: [
+ * 			{ id: 'menu_2_c', label: 'Item C' },
+ * 		]
+ * 	},
+ * 	{ id: 'item_d', label: 'Item D' }
+ * ]
+ * ```
+ *
+ * The menu is build using multiple view classes. The most important are:
+ *
+ * * {@link module:ui/dropdown/menu/dropdownmenunestedmenuview~DropdownMenuNestedMenuView `DropdownMenuNestedMenuView`} - "menu" - provides
+ * a panel with a nested menu, and a button which opens the panel,
+ * * {@link module:ui/dropdown/menu/dropdownmenulistitembuttonview~DropdownMenuListItemButtonView `DropdownMenuListItemButtonView`} -
+ * "button" or "leaf button" (as opposed to buttons provided by `DropdownMenuNestedMenuView`) - should trigger some action when pressed.
+ *
+ * Instances of these two classes are created based on the data provided in definitions. They are assigned proper IDs and labels.
+ * Other view classes build a proper DOM structure around menus and buttons.
+ *
+ * The `DropdownMenuNestedMenuView` instances provides panels, which may include further menus or buttons. These panels are added to
+ * a `BodyCollection` view, which means they are appended outside the DOM editor and UI structure.
+ *
+ * When "leaf button" is pressed, it fires `execute` event which is delegated to `DropdownMenuRootListView` as `menu:execute` event. You
+ * can listen to this event to perform an action:
+ *
+ * ```js
+ * rootListView.on( 'menu:execute', evt => {
+ * 	console.log( evt.source.id ); // E.g. will print 'menu_1_a' when 'Item A' is pressed.
+ * } );
+ * ```
+ *
+ * All menus and "leaf" buttons created from the definition can be easily accessed through {@link ~DropdownMenuRootListView#menus `menus`}
+ * and {@link ~DropdownMenuRootListView#buttons `buttons`} properties.
+ *
+ * For performance reasons, the whole menu structure is created only when `DropdownMenuRootListView` is rendered for the first time.
+ *
+ * It is recommended to use this class together with {@link module:ui/dropdown/utils~addMenuToDropdown `addMenuToDropdown()` helper}.
+ */
+export default class DropdownMenuRootListView extends DropdownMenuListView {
+    /**
+     * Creates an instance of the DropdownMenuRootListView class.
+     *
+     * @param locale
+     * @param bodyCollection
+     * @param definition The definition object used to create the menu structure.
+     */
+    constructor(locale, bodyCollection, definition) {
+        super(locale);
+        /**
+         * Cached array of all menus in the dropdown menu (including nested menus).
+         */
+        this._cachedMenus = [];
+        /**
+         * Cached array of all buttons in the dropdown menu (including buttons in nested menus).
+         */
+        this._cachedButtons = [];
+        this._bodyCollection = bodyCollection;
+        this._definition = definition;
+        this.set('menuPanelClass', undefined);
+    }
+    /**
+     * Returns the array of all menus in the dropdown menu (including nested menus).
+     */
+    get menus() {
+        return Array.from(this._cachedMenus.values());
+    }
+    /**
+     * Returns the array of all buttons in the dropdown menu (including buttons in nested menus).
+     *
+     * Note, that this includes only "leaf" buttons, as specified in the definition passed in constructor. Buttons created as a part of
+     * the nested menus, that open nested menus when hovered or pressed, are not included.
+     */
+    get buttons() {
+        return Array.from(this._cachedButtons.values());
+    }
+    /**
+     * @inheritDoc
+     */
+    render() {
+        this._createStructure(this._definition, null);
+        super.render();
+        DropdownRootMenuBehaviors.toggleMenusAndFocusItemsOnHover(this);
+        DropdownRootMenuBehaviors.closeMenuWhenAnotherOnTheSameLevelOpens(this);
+    }
+    /**
+     * Closes all nested menus.
+     */
+    closeMenus() {
+        this.menus.forEach(menu => {
+            menu.isOpen = false;
+        });
+    }
+    /**
+     * Recursively creates the whole view tree structure for the dropdown menu, according to the passed `definitions`.
+     *
+     * @private
+     */
+    _createStructure(definitions, parentMenuView) {
+        const items = [];
+        for (const def of definitions) {
+            let createdView;
+            if ('menu' in def) {
+                createdView = new DropdownMenuNestedMenuView(this.locale, this._bodyCollection, def.id, def.menu, parentMenuView);
+                createdView.panelView.bind('class').to(this, 'menuPanelClass');
+                if (!parentMenuView) {
+                    createdView.delegate(...DropdownMenuNestedMenuView.DELEGATED_EVENTS).to(this, (name) => `menu:${name}`);
+                }
+                this._cachedMenus.push(createdView);
+                this._createStructure(def.children, createdView);
+            }
+            else {
+                createdView = new DropdownMenuListItemButtonView(this.locale, def.id, def.label);
+                if (!parentMenuView) {
+                    createdView.delegate('execute').to(this, 'menu:execute');
+                }
+                this._cachedButtons.push(createdView);
+            }
+            const listItemView = new DropdownMenuListItemView(this.locale, parentMenuView, createdView);
+            if (!parentMenuView) {
+                listItemView.delegate('mouseenter').to(this, 'menu:mouseenter');
+            }
+            items.push(listItemView);
+        }
+        const targetListView = parentMenuView ? parentMenuView.listView : this;
+        targetListView.items.addMany(items);
+    }
+}

package/src/dropdown/menu/utils.d.ts

@@ -0,0 +1,124 @@
+/**
+ * @license Copyright (c) 2003-2024, 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/menu/utils
+ */
+import type { PositioningFunction } from '@ckeditor/ckeditor5-utils';
+/**
+ * Contains every positioning function used by {@link module:ui/dropdown/menu/dropdownmenunestedmenuview~DropdownMenuNestedMenuView} that
+ * decides where the {@link module:ui/dropdown/menu/dropdownmenunestedmenuview~DropdownMenuNestedMenuView#panelView} should be placed.
+ *
+ * Positioning functions:
+ *
+ *	┌──────┬───────────────┐
+ *	│      │               │
+ *	└──────┤               │
+ *	       │               │
+ *	       │            ES │
+ *	       └───────────────┘
+ *
+ *	┌───────────────┬──────┐
+ *	│               │      │
+ *	│               ├──────┘
+ *	│               │
+ *	│ WS            │
+ *	└───────────────┘
+ *
+ *	       ┌───────────────┐
+ *	       │            EN │
+ *	       │               │
+ *	┌──────┤               │
+ *	│      │               │
+ *	└──────┴───────────────┘
+ *
+ *	┌───────────────┐
+ *	│ WN            │
+ *	│               │
+ *	│               ├──────┐
+ *	│               │      │
+ *	└───────────────┴──────┘
+ */
+export declare const DropdownMenuPanelPositioningFunctions: Record<string, PositioningFunction>;
+/**
+ * Represents the definition of a dropdown menu.
+ */
+export type DropdownNestedMenuDefinition = {
+    /**
+     * Unique ID for the menu.
+     */
+    id: string;
+    /**
+     * The menu name. It is used as a label for the button which opens the menu list.
+     */
+    menu: string;
+    /**
+     * The children of the dropdown menu.
+     */
+    children: DropdownMenuDefinition;
+};
+/**
+ * Represents the definition of a dropdown menu item.
+ */
+export type DropdownMenuButtonDefinition = {
+    /**
+     * Unique ID for the button.
+     */
+    id: string;
+    /**
+     * The label for the button.
+     */
+    label: string;
+};
+/**
+ * A definition for a nestable menu component.
+ *
+ * The menu can be flat and include only top-level items, or it can include multiple levels of nested sub-menus.
+ *
+ * Example:
+ *
+ * ```ts
+ * [
+ * 	{
+ * 		id: 'menu_1',
+ * 		menu: 'Menu 1',
+ * 		children: [
+ * 			{
+ * 				id: 'menu_1_1',
+ * 				menu: 'Nested menu 1',
+ * 				children: [
+ * 					{
+ * 						id: 'item_x',
+ * 						label: 'Item X'
+ * 					}
+ * 				]
+ * 			},
+ * 			{
+ * 				id: 'menu_1_2',
+ * 				menu: 'Nested menu 2',
+ * 				children: [
+ * 					{
+ * 						id: 'item_y',
+ * 						label: 'Item Y'
+ * 					},
+ * 					{
+ * 						id: 'item_z',
+ * 						label: 'Item Z'
+ * 					}
+ * 				]
+ * 			}
+ * 		]
+ * 	},
+ * 	{
+ * 		id: 'top_a',
+ * 		label: 'Top Item A'
+ * 	},
+ * 	{
+ * 		id: 'top_b',
+ * 		label: 'Top Item B'
+ * 	}
+ * ];
+ * ```
+ */
+export type DropdownMenuDefinition = Array<DropdownNestedMenuDefinition | DropdownMenuButtonDefinition>;

package/src/dropdown/menu/utils.js

@@ -0,0 +1,61 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+const NESTED_PANEL_HORIZONTAL_OFFSET = 5;
+/**
+ * Contains every positioning function used by {@link module:ui/dropdown/menu/dropdownmenunestedmenuview~DropdownMenuNestedMenuView} that
+ * decides where the {@link module:ui/dropdown/menu/dropdownmenunestedmenuview~DropdownMenuNestedMenuView#panelView} should be placed.
+ *
+ * Positioning functions:
+ *
+ *	┌──────┬───────────────┐
+ *	│      │               │
+ *	└──────┤               │
+ *	       │               │
+ *	       │            ES │
+ *	       └───────────────┘
+ *
+ *	┌───────────────┬──────┐
+ *	│               │      │
+ *	│               ├──────┘
+ *	│               │
+ *	│ WS            │
+ *	└───────────────┘
+ *
+ *	       ┌───────────────┐
+ *	       │            EN │
+ *	       │               │
+ *	┌──────┤               │
+ *	│      │               │
+ *	└──────┴───────────────┘
+ *
+ *	┌───────────────┐
+ *	│ WN            │
+ *	│               │
+ *	│               ├──────┐
+ *	│               │      │
+ *	└───────────────┴──────┘
+ */
+export const DropdownMenuPanelPositioningFunctions = {
+    eastSouth: buttonRect => ({
+        top: buttonRect.top,
+        left: buttonRect.right - NESTED_PANEL_HORIZONTAL_OFFSET,
+        name: 'es'
+    }),
+    eastNorth: (buttonRect, panelRect) => ({
+        top: buttonRect.top - panelRect.height + buttonRect.height,
+        left: buttonRect.right - NESTED_PANEL_HORIZONTAL_OFFSET,
+        name: 'en'
+    }),
+    westSouth: (buttonRect, panelRect) => ({
+        top: buttonRect.top,
+        left: buttonRect.left - panelRect.width + NESTED_PANEL_HORIZONTAL_OFFSET,
+        name: 'ws'
+    }),
+    westNorth: (buttonRect, panelRect) => ({
+        top: buttonRect.top - panelRect.height + buttonRect.height,
+        left: buttonRect.left - panelRect.width + NESTED_PANEL_HORIZONTAL_OFFSET,
+        name: 'wn'
+    })
+};

package/src/dropdown/utils.d.ts

@@ -9,9 +9,11 @@ import type Model from '../model.js';
 import type DropdownButton from './button/dropdownbutton.js';
 import type { FocusableView } from '../focuscycler.js';
 import type { FalsyValue } from '../template.js';
+import type BodyCollection from '../editorui/bodycollection.js';
 import { type Collection, type Locale } from '@ckeditor/ckeditor5-utils';
 import '../../theme/components/dropdown/toolbardropdown.css';
 import '../../theme/components/dropdown/listdropdown.css';
+import type { DropdownMenuDefinition } from './menu/utils.js';
 /**
  * A helper for creating dropdowns. It creates an instance of a {@link module:ui/dropdown/dropdownview~DropdownView dropdown},
  * with a {@link module:ui/dropdown/button/dropdownbutton~DropdownButton button},
@@ -77,10 +79,66 @@ import '../../theme/components/dropdown/listdropdown.css';
  *
  * @param locale The locale instance.
  * @param ButtonClassOrInstance The dropdown button view class. Needs to implement the
+ * @param behaviorOptions Attributes for the default behavior of the dropdown.
+ *
  * {@link module:ui/dropdown/button/dropdownbutton~DropdownButton} interface.
  * @returns The dropdown view instance.
  */
 export declare function createDropdown(locale: Locale | undefined, ButtonClassOrInstance?: (new (locale?: Locale) => DropdownButton & FocusableView) | (DropdownButton & FocusableView)): DropdownView;
+/**
+ * Adds a menu UI component to a dropdown and sets all common behaviors and interactions between the dropdown and the menu.
+ *
+ * Use this helper to create multi-level dropdown menus that are displayed in a toolbar.
+ *
+ * Internally, it creates an instance of {@link module:ui/dropdown/menu/dropdownmenurootlistview~DropdownMenuRootListView}.
+ *
+ * Example:
+ *
+ * ```ts
+ * const definitions = [
+ * 	{
+ * 		id: 'menu_1',
+ * 		menu: 'Menu 1',
+ * 		children: [
+ * 			{
+ * 				id: 'menu_1_a',
+ * 				label: 'Item A'
+ * 			},
+ * 			{
+ * 				id: 'menu_1_b',
+ * 				label: 'Item B'
+ * 			}
+ * 		]
+ * 	},
+ * 	{
+ * 		id: 'top_a',
+ * 		label: 'Top Item A'
+ * 	},
+ * 	{
+ * 		id: 'top_b',
+ * 		label: 'Top Item B'
+ * 	}
+ * ];
+ *
+ * const dropdownView = createDropdown( editor.locale );
+ *
+ * addMenuToDropdown( dropdownView, editor.ui.view.body, definitions );
+ * ```
+ *
+ * After using this helper, the `dropdown` will fire {@link module:ui/dropdown/dropdownview~DropdownViewEvent `execute`} event when
+ * a nested menu button is pressed.
+ *
+ * The helper will make sure that the `dropdownMenuRootListView` is lazy loaded, i.e., the menu component structure will be initialized
+ * and rendered only after the `dropdown` is opened for the first time.
+ *
+ * @param dropdownView A dropdown instance to which the menu component will be added.
+ * @param body Body collection to which floating menu panels will be added.
+ * @param definition The menu component definition.
+ * @param options.ariaLabel Label used by assistive technologies to describe the top-level menu.
+ */
+export declare function addMenuToDropdown(dropdownView: DropdownView, body: BodyCollection, definition: DropdownMenuDefinition, options?: {
+    ariaLabel?: string;
+}): void;
 /**
  * Adds an instance of {@link module:ui/toolbar/toolbarview~ToolbarView} to a dropdown.
  *