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

package/src/dropdown/menu/dropdownmenubuttonview.js

@@ -0,0 +1,65 @@
+/**
+ * @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/dropdownmenubuttonview
+ */
+import IconView from '../../icon/iconview.js';
+import ListItemButtonView from '../../button/listitembuttonview.js';
+import dropdownArrowIcon from '../../../theme/icons/dropdown-arrow.svg';
+import '../../../theme/components/dropdown/menu/dropdownmenubutton.css';
+/**
+ * Represents a view for a dropdown menu button.
+ */
+export default class DropdownMenuButtonView extends ListItemButtonView {
+    /**
+     * Creates an instance of the dropdown menu button view.
+     *
+     * @param locale The localization services instance.
+     */
+    constructor(locale) {
+        super(locale);
+        const bind = this.bindTemplate;
+        this.set({
+            withText: true,
+            role: 'menuitem'
+        });
+        this.arrowView = this._createArrowView();
+        this.extendTemplate({
+            attributes: {
+                class: [
+                    'ck-dropdown-menu-list__nested-menu__button'
+                ],
+                'aria-haspopup': true,
+                'aria-expanded': this.bindTemplate.to('isOn', value => String(value)),
+                'data-cke-tooltip-disabled': bind.to('isOn')
+            },
+            on: {
+                'mouseenter': bind.to('mouseenter')
+            }
+        });
+    }
+    /**
+     * @inheritDoc
+     */
+    render() {
+        super.render();
+        this.children.add(this.arrowView);
+    }
+    /**
+     * Creates the arrow view instance.
+     *
+     * @private
+     */
+    _createArrowView() {
+        const arrowView = new IconView();
+        arrowView.content = dropdownArrowIcon;
+        arrowView.extendTemplate({
+            attributes: {
+                class: 'ck-dropdown-menu-list__nested-menu__button__arrow'
+            }
+        });
+        return arrowView;
+    }
+}

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

@@ -0,0 +1,17 @@
+/**
+ * @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/dropdownmenulistitembuttonview
+ */
+import type { Locale } from '@ckeditor/ckeditor5-utils';
+import ButtonView from '../../button/buttonview.js';
+import '../../../theme/components/dropdown/menu/dropdownmenulistitembutton.css';
+/**
+ * Represents a view for a button in a dropdown menu list item.
+ */
+export default class DropdownMenuListItemButtonView extends ButtonView {
+    readonly id: string;
+    constructor(locale: Locale, id: string, label: string);
+}

package/src/dropdown/menu/dropdownmenulistitembuttonview.js

@@ -0,0 +1,29 @@
+/**
+ * @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
+ */
+import ButtonView from '../../button/buttonview.js';
+import '../../../theme/components/dropdown/menu/dropdownmenulistitembutton.css';
+/**
+ * Represents a view for a button in a dropdown menu list item.
+ */
+export default class DropdownMenuListItemButtonView extends ButtonView {
+    constructor(locale, id, label) {
+        super(locale);
+        this.id = id;
+        this.set({
+            withText: true,
+            withKeystroke: true,
+            tooltip: false,
+            role: 'menuitem',
+            label
+        });
+        this.extendTemplate({
+            attributes: {
+                class: [
+                    'ck-dropdown-menu-list__nested-menu__item__button'
+                ]
+            }
+        });
+    }
+}

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

@@ -0,0 +1,22 @@
+/**
+ * @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/dropdownmenulistitemview
+ */
+import type { Locale } from '@ckeditor/ckeditor5-utils';
+import type DropdownMenuNestedMenuView from './dropdownmenunestedmenuview.js';
+import ListItemView from '../../list/listitemview.js';
+import DropdownMenuListItemButtonView from './dropdownmenulistitembuttonview.js';
+import '../../../theme/components/dropdown/menu/dropdownmenulistitem.css';
+/**
+ * Represents a view for a single item in a dropdown menu list.
+ */
+export default class DropdownMenuListItemView extends ListItemView {
+    /**
+     * The view representing either a flat item or a nested menu in a dropdown menu list item.
+     */
+    readonly childView: DropdownMenuNestedMenuView | DropdownMenuListItemButtonView;
+    constructor(locale: Locale, parentMenuView: DropdownMenuNestedMenuView | null, childView: DropdownMenuNestedMenuView | DropdownMenuListItemButtonView);
+}

package/src/dropdown/menu/dropdownmenulistitemview.js

@@ -0,0 +1,34 @@
+/**
+ * @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
+ */
+import ListItemView from '../../list/listitemview.js';
+import DropdownMenuListItemButtonView from './dropdownmenulistitembuttonview.js';
+import '../../../theme/components/dropdown/menu/dropdownmenulistitem.css';
+/**
+ * Represents a view for a single item in a dropdown menu list.
+ */
+export default class DropdownMenuListItemView extends ListItemView {
+    constructor(locale, parentMenuView, childView) {
+        super(locale);
+        const bind = this.bindTemplate;
+        this.childView = childView;
+        this.children.add(childView);
+        this.extendTemplate({
+            attributes: {
+                class: [
+                    'ck-dropdown-menu-list__nested-menu__item'
+                ]
+            },
+            on: {
+                'mouseenter': bind.to('mouseenter')
+            }
+        });
+        if (parentMenuView) {
+            this.delegate('mouseenter').to(parentMenuView);
+            if (childView instanceof DropdownMenuListItemButtonView) {
+                childView.delegate('execute').to(parentMenuView);
+            }
+        }
+    }
+}

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

@@ -0,0 +1,24 @@
+/**
+ * @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/dropdownmenulistview
+ */
+import type { Locale } from '@ckeditor/ckeditor5-utils';
+import ListView from '../../list/listview.js';
+/**
+ * Represents a dropdown menu list view.
+ */
+export default class DropdownMenuListView extends ListView {
+    /**
+     * Represents whether the dropdown menu list view is visible or not.
+     */
+    isVisible: boolean;
+    /**
+     * Creates an instance of the dropdown menu list view.
+     *
+     * @param locale The localization services instance.
+     */
+    constructor(locale: Locale);
+}

package/src/dropdown/menu/dropdownmenulistview.js

@@ -0,0 +1,29 @@
+/**
+ * @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
+ */
+import ListView from '../../list/listview.js';
+/**
+ * Represents a dropdown menu list view.
+ */
+export default class DropdownMenuListView extends ListView {
+    /**
+     * Creates an instance of the dropdown menu list view.
+     *
+     * @param locale The localization services instance.
+     */
+    constructor(locale) {
+        super(locale);
+        const bind = this.bindTemplate;
+        this.role = 'menu';
+        this.set('isVisible', true);
+        this.extendTemplate({
+            attributes: {
+                class: [
+                    'ck-dropdown-menu-list',
+                    bind.if('isVisible', 'ck-hidden', value => !value)
+                ]
+            }
+        });
+    }
+}

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

@@ -0,0 +1,34 @@
+/**
+ * @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/dropdownmenunestedmenupanelview
+ */
+import type { Locale } from '@ckeditor/ckeditor5-utils';
+import type { FocusableView } from '../../focuscycler.js';
+import BalloonPanelView from '../../panel/balloon/balloonpanelview.js';
+import '../../../theme/components/dropdown/menu/dropdownmenupanel.css';
+/**
+ * Represents the view for the dropdown menu panel.
+ */
+export default class DropdownMenuNestedMenuPanelView extends BalloonPanelView implements FocusableView {
+    /**
+     * Creates an instance of the menu panel view.
+     *
+     * @param locale The localization services instance.
+     */
+    constructor(locale?: Locale);
+    /**
+     * Focuses the first child of the panel (default) or the last one if the `direction` is `-1`.
+     *
+     * @param direction The direction to focus. Default is `1`.
+     */
+    focus(direction?: -1 | 1): void;
+}
+/**
+ * The names of the positions of the {@link module:ui/dropdown/menu/dropdownmenunestedmenupanelview~DropdownMenuNestedMenuPanelView}.
+ *
+ * They are reflected as CSS class suffixes on the panel view element.
+ */
+export type DropdownMenuNestedMenuPanelPosition = 'es' | 'ws' | 'en' | 'wn' | 'w' | 'e';

package/src/dropdown/menu/dropdownmenunestedmenupanelview.js

@@ -0,0 +1,63 @@
+/**
+ * @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
+ */
+import BalloonPanelView from '../../panel/balloon/balloonpanelview.js';
+import '../../../theme/components/dropdown/menu/dropdownmenupanel.css';
+/**
+ * Represents the view for the dropdown menu panel.
+ */
+export default class DropdownMenuNestedMenuPanelView extends BalloonPanelView {
+    /**
+     * Creates an instance of the menu panel view.
+     *
+     * @param locale The localization services instance.
+     */
+    constructor(locale) {
+        super(locale);
+        const bind = this.bindTemplate;
+        this.set({
+            isVisible: false,
+            position: 'se',
+            class: null,
+            top: 0,
+            left: 0
+        });
+        this.extendTemplate({
+            tag: 'div',
+            attributes: {
+                class: [
+                    'ck-reset',
+                    'ck-dropdown-menu__nested-menu__panel'
+                ],
+                tabindex: '-1'
+            },
+            on: {
+                // Drag and drop in the panel should not break the selection in the editor.
+                // https://github.com/ckeditor/ckeditor5-ui/issues/228
+                selectstart: bind.to(evt => {
+                    if (evt.target.tagName.toLocaleLowerCase() === 'input') {
+                        return;
+                    }
+                    evt.preventDefault();
+                })
+            }
+        });
+    }
+    /**
+     * Focuses the first child of the panel (default) or the last one if the `direction` is `-1`.
+     *
+     * @param direction The direction to focus. Default is `1`.
+     */
+    focus(direction = 1) {
+        const { content } = this;
+        if (content.length) {
+            if (direction === 1) {
+                content.first.focus();
+            }
+            else {
+                content.last.focus();
+            }
+        }
+    }
+}

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

@@ -0,0 +1,131 @@
+/**
+ * @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/dropdownmenunestedmenuview
+ */
+import { FocusTracker, KeystrokeHandler, type PositioningFunction, type Locale } from '@ckeditor/ckeditor5-utils';
+import type { FocusableView } from '../../focuscycler.js';
+import type BodyCollection from '../../editorui/bodycollection.js';
+import DropdownMenuButtonView from './dropdownmenubuttonview.js';
+import DropdownMenuListView from './dropdownmenulistview.js';
+import View from '../../view.js';
+import DropdownMenuNestedMenuPanelView, { type DropdownMenuNestedMenuPanelPosition } from './dropdownmenunestedmenupanelview.js';
+import '../../../theme/components/dropdown/menu/dropdownmenu.css';
+/**
+ * Represents a nested menu view.
+ */
+export default class DropdownMenuNestedMenuView extends View implements FocusableView {
+    /**
+     * An array of delegated events for the dropdown menu definition controller.
+     * These events are delegated to the dropdown menu element.
+     */
+    static readonly DELEGATED_EVENTS: readonly ["mouseenter", "execute", "change:isOpen"];
+    readonly id: string;
+    /**
+     * Button of the menu view.
+     */
+    readonly buttonView: DropdownMenuButtonView;
+    /**
+     * Panel of the menu. It hosts children of the menu.
+     */
+    readonly panelView: DropdownMenuNestedMenuPanelView;
+    /**
+     * List of nested menu entries.
+     */
+    readonly listView: DropdownMenuListView;
+    /**
+     * Tracks information about the DOM focus in the menu.
+     */
+    readonly focusTracker: FocusTracker;
+    /**
+     * Instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}. It manages
+     * keystrokes of the menu.
+     */
+    readonly keystrokes: KeystrokeHandler;
+    /**
+     * Controls whether the menu is open, i.e. shows or hides the {@link #panelView panel}.
+     *
+     * @observable
+     */
+    isOpen: boolean;
+    /**
+     * Controls whether the menu is enabled, i.e. its {@link #buttonView} can be clicked.
+     *
+     * @observable
+     */
+    isEnabled: boolean;
+    /**
+     * (Optional) The additional CSS class set on the menu {@link #element}.
+     *
+     * @observable
+     */
+    class: string | undefined;
+    /**
+     * The name of the position of the {@link #panelView}, relative to the menu.
+     *
+     * **Note**: The value is updated each time the panel gets {@link #isOpen open}.
+     *
+     * @observable
+     * @default 'w'
+     */
+    panelPosition: DropdownMenuNestedMenuPanelPosition;
+    /**
+     * The parent menu view of the menu. It is `null` for top-level menus.
+     *
+     * @observable
+     * @default null
+     */
+    readonly parentMenuView: DropdownMenuNestedMenuView | null;
+    private _bodyCollection;
+    /**
+     * Creates a new instance of the DropdownMenuView class.
+     *
+     * @param locale
+     * @param bodyCollection
+     * @param id
+     * @param label The label for the dropdown menu button.
+     * @param parentMenuView The parent dropdown menu view, if any.
+     */
+    constructor(locale: Locale, bodyCollection: BodyCollection, id: string, label: string, parentMenuView: DropdownMenuNestedMenuView | null);
+    /**
+     * An array of positioning functions used to determine the position of the dropdown menu panel.
+     * The order of the functions in the array determines the priority of the positions to be tried.
+     * The first function that returns a valid position will be used.
+     *
+     * @returns {Array<PositioningFunction>} An array of positioning functions.
+     * @internal
+     */
+    get _panelPositions(): Array<PositioningFunction>;
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * @inheritDoc
+     */
+    focus(): void;
+    private _handleParentMenuView;
+    /**
+     * Attach all keyboard behaviors for the menu view.
+     */
+    private _attachBehaviors;
+    /**
+     * Mounts the portal view in the body when the menu is open and removes it when the menu is closed.
+     * Binds keystrokes to the portal view when the menu is open.
+     */
+    private _mountPanelOnOpen;
+    /**
+     * Removes the panel view from the editor's body and removes it from the focus tracker.
+     */
+    private _removePanelFromBody;
+    /**
+     * Adds the panel view to the editor's body and sets up event listeners.
+     */
+    private _addPanelToBody;
+}

package/src/dropdown/menu/dropdownmenunestedmenuview.js

@@ -0,0 +1,191 @@
+/**
+ * @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/dropdownmenunestedmenuview
+ */
+import { FocusTracker, KeystrokeHandler, global } from '@ckeditor/ckeditor5-utils';
+import DropdownMenuButtonView from './dropdownmenubuttonview.js';
+import DropdownMenuListView from './dropdownmenulistview.js';
+import { DropdownMenuPanelPositioningFunctions } from './utils.js';
+import { DropdownMenuBehaviors } from './dropdownmenubehaviors.js';
+import View from '../../view.js';
+import DropdownMenuNestedMenuPanelView from './dropdownmenunestedmenupanelview.js';
+import '../../../theme/components/dropdown/menu/dropdownmenu.css';
+/**
+ * Represents a nested menu view.
+ */
+class DropdownMenuNestedMenuView extends View {
+    /**
+     * Creates a new instance of the DropdownMenuView class.
+     *
+     * @param locale
+     * @param bodyCollection
+     * @param id
+     * @param label The label for the dropdown menu button.
+     * @param parentMenuView The parent dropdown menu view, if any.
+     */
+    constructor(locale, bodyCollection, id, label, parentMenuView) {
+        super(locale);
+        this._bodyCollection = bodyCollection;
+        this.id = id;
+        this.set({
+            isOpen: false,
+            isEnabled: true,
+            panelPosition: 'w',
+            class: undefined,
+            parentMenuView: null
+        });
+        this.keystrokes = new KeystrokeHandler();
+        this.focusTracker = new FocusTracker();
+        this.buttonView = new DropdownMenuButtonView(locale);
+        this.buttonView.delegate('mouseenter').to(this);
+        this.buttonView.bind('isOn', 'isEnabled').to(this, 'isOpen', 'isEnabled');
+        this.buttonView.label = label;
+        this.panelView = new DropdownMenuNestedMenuPanelView(locale);
+        this.panelView.isVisible = true;
+        this.listView = new DropdownMenuListView(locale);
+        this.listView.bind('ariaLabel').to(this.buttonView, 'label');
+        this.panelView.content.add(this.listView);
+        const bind = this.bindTemplate;
+        this.setTemplate({
+            tag: 'div',
+            attributes: {
+                class: [
+                    'ck',
+                    'ck-dropdown-menu-list__nested-menu',
+                    bind.to('class'),
+                    bind.if('isEnabled', 'ck-disabled', value => !value)
+                ],
+                role: 'presentation'
+            },
+            children: [
+                this.buttonView
+            ]
+        });
+        this.parentMenuView = parentMenuView;
+        if (this.parentMenuView) {
+            this._handleParentMenuView();
+        }
+        this._attachBehaviors();
+    }
+    /**
+     * An array of positioning functions used to determine the position of the dropdown menu panel.
+     * The order of the functions in the array determines the priority of the positions to be tried.
+     * The first function that returns a valid position will be used.
+     *
+     * @returns {Array<PositioningFunction>} An array of positioning functions.
+     * @internal
+     */
+    get _panelPositions() {
+        const { westSouth, eastSouth, westNorth, eastNorth } = DropdownMenuPanelPositioningFunctions;
+        if (this.locale.uiLanguageDirection === 'ltr') {
+            return [eastSouth, eastNorth, westSouth, westNorth];
+        }
+        else {
+            return [westSouth, westNorth, eastSouth, eastNorth];
+        }
+    }
+    /**
+     * @inheritDoc
+     */
+    render() {
+        super.render();
+        this.panelView.render();
+        this.focusTracker.add(this.buttonView.element);
+        this.focusTracker.add(this.panelView.element);
+        // Listen for keystrokes coming from within #element.
+        this.keystrokes.listenTo(this.element);
+        this._mountPanelOnOpen();
+    }
+    /**
+     * @inheritDoc
+     */
+    destroy() {
+        this._removePanelFromBody();
+        this.panelView.destroy();
+        super.destroy();
+    }
+    /**
+     * @inheritDoc
+     */
+    focus() {
+        this.buttonView.focus();
+    }
+    _handleParentMenuView() {
+        // Propagate events from this component to parent-menu.
+        this.delegate(...DropdownMenuNestedMenuView.DELEGATED_EVENTS).to(this.parentMenuView);
+        // Close this menu if its parent closes.
+        DropdownMenuBehaviors.closeOnParentClose(this, this.parentMenuView);
+    }
+    /**
+     * Attach all keyboard behaviors for the menu view.
+     */
+    _attachBehaviors() {
+        DropdownMenuBehaviors.openOnButtonClick(this);
+        DropdownMenuBehaviors.openAndFocusOnEnterKeyPress(this);
+        DropdownMenuBehaviors.openOnArrowRightKey(this);
+        DropdownMenuBehaviors.closeOnEscKey(this);
+        DropdownMenuBehaviors.closeOnArrowLeftKey(this);
+    }
+    /**
+     * Mounts the portal view in the body when the menu is open and removes it when the menu is closed.
+     * Binds keystrokes to the portal view when the menu is open.
+     */
+    _mountPanelOnOpen() {
+        const { panelView } = this;
+        this.on('change:isOpen', (evt, name, isOpen) => {
+            // Ensure that the event was triggered by this instance.
+            // TODO: Remove checking `evt.source` if `change:isOpen` is no longer delegated.
+            if (evt.source !== this) {
+                return;
+            }
+            // Removes the panel view from the body when the menu is closed.
+            if (!isOpen && this._bodyCollection.has(panelView)) {
+                this._removePanelFromBody();
+                return;
+            }
+            // Adds the panel view to the body when the menu is open.
+            if (isOpen && !this._bodyCollection.has(panelView)) {
+                this._addPanelToBody();
+            }
+        });
+    }
+    /**
+     * Removes the panel view from the editor's body and removes it from the focus tracker.
+     */
+    _removePanelFromBody() {
+        const { panelView, keystrokes } = this;
+        if (this._bodyCollection.has(panelView)) {
+            this._bodyCollection.remove(panelView);
+            keystrokes.stopListening(panelView.element);
+        }
+    }
+    /**
+     * Adds the panel view to the editor's body and sets up event listeners.
+     */
+    _addPanelToBody() {
+        const { panelView, buttonView, keystrokes } = this;
+        if (!this._bodyCollection.has(panelView)) {
+            this._bodyCollection.add(panelView);
+            keystrokes.listenTo(panelView.element);
+            panelView.pin({
+                positions: this._panelPositions,
+                limiter: global.document.body,
+                element: panelView.element,
+                target: buttonView.element,
+                fitInViewport: true
+            });
+        }
+    }
+}
+/**
+ * An array of delegated events for the dropdown menu definition controller.
+ * These events are delegated to the dropdown menu element.
+ */
+// Due to some spaghetti code we need to delegate `change:isOpen`.
+DropdownMenuNestedMenuView.DELEGATED_EVENTS = [
+    'mouseenter', 'execute', 'change:isOpen'
+];
+export default DropdownMenuNestedMenuView;