@ckeditor/ckeditor5-ui 0.0.0-internal-20241017.0

package/src/menubar/menubarmenubuttonview.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @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/menubar/menubarmenubuttonview
+ */
+import IconView from '../icon/iconview.js';
+import ListItemButtonView from '../button/listitembuttonview.js';
+import type { Locale } from '@ckeditor/ckeditor5-utils';
+import '../../theme/components/menubar/menubarmenubutton.css';
+/**
+ * A menu {@link module:ui/menubar/menubarmenuview~MenuBarMenuView#buttonView} class. Buttons like this one
+ * open both top-level bar menus as well as sub-menus.
+ */
+export default class MenuBarMenuButtonView extends ListItemButtonView {
+    /**
+     * An icon that displays an arrow to indicate a direction of the menu.
+     */
+    readonly arrowView: IconView;
+    /**
+     * Creates an instance of the menu bar button view.
+     *
+     * @param locale The localization services instance.
+     */
+    constructor(locale: Locale);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * Creates the {@link #arrowView} instance.
+     */
+    private _createArrowView;
+}

package/src/menubar/menubarmenubuttonview.js

@@ -0,0 +1,64 @@
+/**
+ * @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/menubar/menubarmenubuttonview
+ */
+import IconView from '../icon/iconview.js';
+import ListItemButtonView from '../button/listitembuttonview.js';
+import dropdownArrowIcon from '../../theme/icons/dropdown-arrow.svg';
+import '../../theme/components/menubar/menubarmenubutton.css';
+/**
+ * A menu {@link module:ui/menubar/menubarmenuview~MenuBarMenuView#buttonView} class. Buttons like this one
+ * open both top-level bar menus as well as sub-menus.
+ */
+export default class MenuBarMenuButtonView extends ListItemButtonView {
+    /**
+     * Creates an instance of the menu bar 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-menu-bar__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 {@link #arrowView} instance.
+     */
+    _createArrowView() {
+        const arrowView = new IconView();
+        arrowView.content = dropdownArrowIcon;
+        arrowView.extendTemplate({
+            attributes: {
+                class: 'ck-menu-bar__menu__button__arrow'
+            }
+        });
+        return arrowView;
+    }
+}

package/src/menubar/menubarmenulistitembuttonview.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @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/menubar/menubarmenulistitembuttonview
+ */
+import type { Locale } from '@ckeditor/ckeditor5-utils';
+import ListItemButtonView from '../button/listitembuttonview.js';
+import '../../theme/components/menubar/menubarmenulistitembutton.css';
+/**
+ * A menu bar list button view. Buttons like this one execute user actions.
+ */
+export default class MenuBarMenuListItemButtonView extends ListItemButtonView {
+    /**
+     * Creates an instance of the menu bar list button view.
+     *
+     * @param locale The localization services instance.
+     */
+    constructor(locale: Locale);
+}

package/src/menubar/menubarmenulistitembuttonview.js

@@ -0,0 +1,30 @@
+/**
+ * @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 ListItemButtonView from '../button/listitembuttonview.js';
+import '../../theme/components/menubar/menubarmenulistitembutton.css';
+/**
+ * A menu bar list button view. Buttons like this one execute user actions.
+ */
+export default class MenuBarMenuListItemButtonView extends ListItemButtonView {
+    /**
+     * Creates an instance of the menu bar list button view.
+     *
+     * @param locale The localization services instance.
+     */
+    constructor(locale) {
+        super(locale);
+        this.set({
+            withText: true,
+            withKeystroke: true,
+            tooltip: false,
+            role: 'menuitem'
+        });
+        this.extendTemplate({
+            attributes: {
+                class: ['ck-menu-bar__menu__item__button']
+            }
+        });
+    }
+}

package/src/menubar/menubarmenulistitemfiledialogbuttonview.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @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/menubar/menubarmenulistitemfiledialogbuttonview
+ */
+import type { Locale } from '@ckeditor/ckeditor5-utils';
+import { FileDialogListItemButtonView } from '../button/filedialogbuttonview.js';
+import '../../theme/components/menubar/menubarmenulistitembutton.css';
+/**
+ * A menu bar list file dialog button view. Buttons like this one execute user actions.
+ *
+ * This component provides a button that opens the native file selection dialog.
+ */
+export default class MenuBarMenuListItemFileDialogButtonView extends FileDialogListItemButtonView {
+    /**
+     * Creates an instance of the menu bar list button view.
+     *
+     * @param locale The localization services instance.
+     */
+    constructor(locale: Locale);
+}

package/src/menubar/menubarmenulistitemfiledialogbuttonview.js

@@ -0,0 +1,32 @@
+/**
+ * @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 { FileDialogListItemButtonView } from '../button/filedialogbuttonview.js';
+import '../../theme/components/menubar/menubarmenulistitembutton.css';
+/**
+ * A menu bar list file dialog button view. Buttons like this one execute user actions.
+ *
+ * This component provides a button that opens the native file selection dialog.
+ */
+export default class MenuBarMenuListItemFileDialogButtonView extends FileDialogListItemButtonView {
+    /**
+     * Creates an instance of the menu bar list button view.
+     *
+     * @param locale The localization services instance.
+     */
+    constructor(locale) {
+        super(locale);
+        this.set({
+            withText: true,
+            withKeystroke: true,
+            tooltip: false,
+            role: 'menuitem'
+        });
+        this.extendTemplate({
+            attributes: {
+                class: ['ck-menu-bar__menu__item__button']
+            }
+        });
+    }
+}

package/src/menubar/menubarmenulistitemview.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @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/menubar/menubarmenulistitemview
+ */
+import type { Locale } from '@ckeditor/ckeditor5-utils';
+import ListItemView from '../list/listitemview.js';
+import type MenuBarMenuView from './menubarmenuview.js';
+import '../../theme/components/menubar/menubarmenulistitem.css';
+/**
+ * A menu bar list item view, a child of {@link module:ui/menubar/menubarmenulistview~MenuBarMenuListView}.
+ *
+ * Populate this item with a {@link module:ui/menubar/menubarmenulistitembuttonview~MenuBarMenuListItemButtonView} instance
+ * or a {@link module:ui/menubar/menubarmenuview~MenuBarMenuView} instance to create a sub-menu.
+ */
+export default class MenuBarMenuListItemView extends ListItemView {
+    /**
+     * Creates an instance of the list item view.
+     *
+     * @param locale The localization services instance.
+     */
+    constructor(locale: Locale, parentMenuView: MenuBarMenuView);
+}

package/src/menubar/menubarmenulistitemview.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 '../../theme/components/menubar/menubarmenulistitem.css';
+/**
+ * A menu bar list item view, a child of {@link module:ui/menubar/menubarmenulistview~MenuBarMenuListView}.
+ *
+ * Populate this item with a {@link module:ui/menubar/menubarmenulistitembuttonview~MenuBarMenuListItemButtonView} instance
+ * or a {@link module:ui/menubar/menubarmenuview~MenuBarMenuView} instance to create a sub-menu.
+ */
+export default class MenuBarMenuListItemView extends ListItemView {
+    /**
+     * Creates an instance of the list item view.
+     *
+     * @param locale The localization services instance.
+     */
+    constructor(locale, parentMenuView) {
+        super(locale);
+        const bind = this.bindTemplate;
+        this.extendTemplate({
+            attributes: {
+                class: [
+                    'ck-menu-bar__menu__item'
+                ]
+            },
+            on: {
+                'mouseenter': bind.to('mouseenter')
+            }
+        });
+        this.delegate('mouseenter').to(parentMenuView);
+    }
+}

package/src/menubar/menubarmenulistview.d.ts

@@ -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
+ */
+/**
+ * @module ui/menubar/menubarmenulistview
+ */
+import type { Locale } from '@ckeditor/ckeditor5-utils';
+import ListView from '../list/listview.js';
+/**
+ * A list of menu bar items, a child of {@link module:ui/menubar/menubarmenuview~MenuBarMenuView#panelView}.
+ *
+ * Use this class to create a list of items (options, buttons) to be displayed in a menu bar.
+ *
+ * To populate this list, use {@link module:ui/menubar/menubarmenulistitemview~MenuBarMenuListItemView} instances.
+ */
+export default class MenuBarMenuListView extends ListView {
+    /**
+     * Creates an instance of the list view.
+     *
+     * @param locale The localization services instance.
+     */
+    constructor(locale: Locale);
+    /**
+     * This method adds empty space if there is any toggleable item in the list.
+     * It makes the list properly aligned.
+     */
+    private _setItemsCheckSpace;
+}

package/src/menubar/menubarmenulistview.js

@@ -0,0 +1,72 @@
+/**
+ * @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 ListView from '../list/listview.js';
+import ListItemButtonView from '../button/listitembuttonview.js';
+import ButtonView from '../button/buttonview.js';
+/**
+ * A list of menu bar items, a child of {@link module:ui/menubar/menubarmenuview~MenuBarMenuView#panelView}.
+ *
+ * Use this class to create a list of items (options, buttons) to be displayed in a menu bar.
+ *
+ * To populate this list, use {@link module:ui/menubar/menubarmenulistitemview~MenuBarMenuListItemView} instances.
+ */
+export default class MenuBarMenuListView extends ListView {
+    /**
+     * Creates an instance of the list view.
+     *
+     * @param locale The localization services instance.
+     */
+    constructor(locale) {
+        super(locale);
+        this.role = 'menu';
+        this.items.on('change', this._setItemsCheckSpace.bind(this));
+    }
+    /**
+     * This method adds empty space if there is any toggleable item in the list.
+     * It makes the list properly aligned.
+     */
+    _setItemsCheckSpace() {
+        const hasAnyToggleableItem = (Array
+            .from(this.items)
+            .some(item => {
+            const listButtonView = pickListButtonMenuViewIfPresent(item);
+            return listButtonView && listButtonView.isToggleable;
+        }));
+        this.items.forEach(item => {
+            const listButtonView = pickListButtonMenuViewIfPresent(item);
+            if (listButtonView) {
+                listButtonView.hasCheckSpace = hasAnyToggleableItem;
+            }
+        });
+    }
+}
+/**
+ * Picks the first button menu view from the given item if present.
+ *
+ * @param item The item to check for a button menu view.
+ * @returns The first button menu view found in the item, or `null` if not found.
+ */
+function pickListButtonMenuViewIfPresent(item) {
+    if (!(item instanceof ListItemView)) {
+        return null;
+    }
+    return item
+        .children
+        .map(child => isNestedMenuLikeView(child) ? child.buttonView : child)
+        .find(item => item instanceof ListItemButtonView);
+}
+/**
+ * Checks if the given item is a nested menu-like view. `MenuBarMenuView` imports this file
+ * so to avoid circular dependencies, this function is defined in more generic way.
+ *
+ * @param item The item to check.
+ * @returns `true` if the item is a nested menu-like view, `false` otherwise.
+ */
+function isNestedMenuLikeView(item) {
+    return (typeof item === 'object' &&
+        'buttonView' in item &&
+        item.buttonView instanceof ButtonView);
+}

package/src/menubar/menubarmenupanelview.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @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/menubar/menubarmenupanelview
+ */
+import { type Locale } from '@ckeditor/ckeditor5-utils';
+import type { FocusableView } from '../focuscycler.js';
+import type ViewCollection from '../viewcollection.js';
+import View from '../view.js';
+import '../../theme/components/menubar/menubarmenupanel.css';
+/**
+ * A view representing a {@link module:ui/menubar/menubarmenuview~MenuBarMenuView#panelView} of a menu.
+ */
+export default class MenuBarMenuPanelView extends View implements FocusableView {
+    /**
+     * Collection of the child views in this panel.
+     */
+    readonly children: ViewCollection<FocusableView>;
+    /**
+     * Controls whether the panel is visible.
+     *
+     * @observable
+     */
+    isVisible: boolean;
+    /**
+     * The name of the position of the panel, relative to the parent.
+     *
+     * This property is reflected in the CSS class suffix set to {@link #element} that controls
+     * the position of the panel.
+     *
+     * @observable
+     * @default 'se'
+     */
+    position: MenuBarMenuPanelPosition;
+    /**
+     * 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`.
+     */
+    focus(direction?: -1 | 1): void;
+}
+/**
+ * The names of the positions of the {@link module:ui/menubar/menubarmenupanelview~MenuBarMenuPanelView}.
+ *
+ * They are reflected as CSS class suffixes on the panel view element.
+ */
+export type MenuBarMenuPanelPosition = 'se' | 'sw' | 'ne' | 'nw' | 'w' | 'e';

package/src/menubar/menubarmenupanelview.js

@@ -0,0 +1,60 @@
+/**
+ * @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 View from '../view.js';
+import '../../theme/components/menubar/menubarmenupanel.css';
+/**
+ * A view representing a {@link module:ui/menubar/menubarmenuview~MenuBarMenuView#panelView} of a menu.
+ */
+export default class MenuBarMenuPanelView extends View {
+    /**
+     * 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);
+        this.set('position', 'se');
+        this.children = this.createCollection();
+        this.setTemplate({
+            tag: 'div',
+            attributes: {
+                class: [
+                    'ck',
+                    'ck-reset',
+                    'ck-menu-bar__menu__panel',
+                    bind.to('position', value => `ck-menu-bar__menu__panel_position_${value}`),
+                    bind.if('isVisible', 'ck-hidden', value => !value)
+                ],
+                tabindex: '-1'
+            },
+            children: this.children,
+            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`.
+     */
+    focus(direction = 1) {
+        if (this.children.length) {
+            if (direction === 1) {
+                this.children.first.focus();
+            }
+            else {
+                this.children.last.focus();
+            }
+        }
+    }
+}

package/src/menubar/menubarmenuview.d.ts

@@ -0,0 +1,109 @@
+/**
+ * @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/menubar/menubarmenuview
+ */
+import { FocusTracker, KeystrokeHandler, type Locale, type PositioningFunction } from '@ckeditor/ckeditor5-utils';
+import MenuBarMenuButtonView from './menubarmenubuttonview.js';
+import type { FocusableView } from '../focuscycler.js';
+import View from '../view.js';
+import { default as MenuBarMenuPanelView, type MenuBarMenuPanelPosition } from './menubarmenupanelview.js';
+import '../../theme/components/menubar/menubarmenu.css';
+/**
+ * A menu view for the {@link module:ui/menubar/menubarview~MenuBarView}. Menus are building blocks of the menu bar,
+ * they host other sub-menus and menu items (buttons) that users can interact with.
+ */
+export default class MenuBarMenuView extends View implements FocusableView {
+    /**
+     * Button of the menu view.
+     */
+    readonly buttonView: MenuBarMenuButtonView;
+    /**
+     * Panel of the menu. It hosts children of the menu.
+     */
+    readonly panelView: MenuBarMenuPanelView;
+    /**
+     * 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: MenuBarMenuPanelPosition;
+    /**
+     * The parent menu view of the menu. It is `null` for top-level menus.
+     *
+     * See {@link module:ui/menubar/menubarview~MenuBarView#registerMenu}.
+     */
+    parentMenuView: MenuBarMenuView | null;
+    /**
+     * Creates an instance of the menu view.
+     *
+     * @param locale The localization services instance.
+     */
+    constructor(locale: Locale);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * Attach all keyboard behaviors for the menu bar view.
+     *
+     * @internal
+     */
+    _attachBehaviors(): void;
+    /**
+     * Fires `arrowright` and `arrowleft` events when the user pressed corresponding arrow keys.
+     */
+    private _propagateArrowKeystrokeEvents;
+    /**
+     * Sets the position of the panel when the menu opens. The panel is positioned
+     * so that it optimally uses the available space in the viewport.
+     */
+    private _repositionPanelOnOpen;
+    /**
+     * @inheritDoc
+     */
+    focus(): void;
+    /**
+     * Positioning functions for the {@link #panelView} . They change depending on the role of the menu (top-level vs sub-menu) in
+     * the {@link module:ui/menubar/menubarview~MenuBarView menu bar} and the UI language direction.
+     */
+    get _panelPositions(): Array<PositioningFunction>;
+    /**
+     * A function used to calculate the optimal position for the dropdown panel.
+     *
+     * Referenced for unit testing purposes.
+     */
+    private static _getOptimalPosition;
+}