@ckeditor/ckeditor5-ui 43.0.0 → 43.1.0-alpha.1

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

@@ -0,0 +1,128 @@
+/**
+ * @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
+ */
+/**
+ * @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/dist/dropdown/utils.d.ts

@@ -13,9 +13,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},
@@ -81,10 +83,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.
  *

package/dist/editableui/editableuiview.d.ts

@@ -38,7 +38,7 @@ export default class EditableUIView extends View {
     /**
      * The element which is the main editable element (usually the one with `contentEditable="true"`).
      */
-    private _editableElement;
+    protected _editableElement: HTMLElement | null | undefined;
     /**
      * Whether an external {@link #_editableElement} was passed into the constructor, which also means
      * the view will not render its {@link #template}.

package/dist/editableui/inline/inlineeditableuiview.d.ts

@@ -17,10 +17,9 @@ import type { Locale } from '@ckeditor/ckeditor5-utils';
  */
 export default class InlineEditableUIView extends EditableUIView {
     /**
-     * A function that gets called with the instance of this view as an argument and should return a string that
-     * represents the label of the editable for assistive technologies.
+     * The cached options object passed to the constructor.
      */
-    private readonly _generateLabel;
+    private readonly _options;
     /**
      * Creates an instance of the InlineEditableUIView class.
      *
@@ -30,15 +29,20 @@ export default class InlineEditableUIView extends EditableUIView {
      * {@link module:ui/editableui/editableuiview~EditableUIView}
      * will create it. Otherwise, the existing element will be used.
      * @param options Additional configuration of the view.
-     * @param options.label A function that gets called with the instance of this view as an argument
-     * and should return a string that represents the label of the editable for assistive technologies. If not provided,
-     * a default label generator is used.
+     * @param options.label The label of the editable for assistive technologies. If not provided, a default label is used or,
+     * the existing `aria-label` attribute value from the specified `editableElement` is preserved.
      */
-    constructor(locale: Locale, editingView: EditingView, editableElement?: HTMLElement, options?: {
-        label?: (view: InlineEditableUIView) => string;
-    });
+    constructor(locale: Locale, editingView: EditingView, editableElement?: HTMLElement, options?: InlineEditableUIViewOptions);
     /**
      * @inheritDoc
      */
     render(): void;
+    /**
+     * Returns a normalized label for the editable view based on the environment.
+     */
+    getEditableAriaLabel(): string;
 }
+type InlineEditableUIViewOptions = {
+    label?: ((view: InlineEditableUIView) => string) | string | Record<string, string>;
+};
+export {};

package/dist/editorui/editorui.d.ts

@@ -286,6 +286,10 @@ export default abstract class EditorUI extends /* #__PURE__ */ EditorUI_base {
      * @param data The payload carried by the `scrollToTheSelection` event.
      */
     private _handleScrollToTheSelection;
+    /**
+     * Ensures that the focus tracker is aware of all views' DOM elements in the body collection.
+     */
+    private _bindBodyCollectionWithFocusTracker;
 }
 /**
  * Fired when the editor UI is ready.

package/dist/index-editor.css

@@ -352,6 +352,22 @@ a.ck.ck-button{
 			z-index:calc(var(--ck-z-default) + 1);
 		}
 
+.ck.ck-dropdown-menu-list__nested-menu__button > .ck-dropdown-menu-list__nested-menu__button__arrow{
+	pointer-events:none;
+	z-index:var(--ck-z-default);
+}
+
+.ck.ck-dropdown-menu__nested-menu__panel{
+	position:absolute;
+	max-height:314px;
+	overflow-y:auto;
+	z-index:calc(var(--ck-z-panel) + 1);
+}
+
+.ck.ck-dropdown-menu-list__nested-menu{
+	display:block;
+}
+
 .ck.ck-aria-live-announcer{
 	position:absolute;
 	left:-10000px;

package/dist/index.css

@@ -489,6 +489,37 @@ a.ck.ck-button {
 			z-index: calc(var(--ck-z-default) + 1);
 		}
 
+/*
+ * 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
+ */
+
+.ck.ck-dropdown-menu-list__nested-menu__button > .ck-dropdown-menu-list__nested-menu__button__arrow {
+	pointer-events: none;
+	z-index: var(--ck-z-default);
+}
+
+/*
+ * 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
+ */
+
+.ck.ck-dropdown-menu__nested-menu__panel {
+	position: absolute;
+	max-height: 314px; /* With the default settings, this is equal to 10 menu items. */
+	overflow-y: auto;
+	z-index: calc(var(--ck-z-panel) + 1);
+}
+
+/*
+ * 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
+ */
+
+.ck.ck-dropdown-menu-list__nested-menu {
+	display: block;
+}
+
 /*
  * 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