@ckeditor/ckeditor5-ui 47.6.1-alpha.1 → 48.0.0-alpha.0

package/src/dropdown/dropdownview.js

@@ -1,438 +0,0 @@
-/**
- * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
- */
-/**
- * @module ui/dropdown/dropdownview
- */
-import { View } from '../view.js';
-import { KeystrokeHandler, FocusTracker, getOptimalPosition } from '@ckeditor/ckeditor5-utils';
-import '../../theme/components/dropdown/dropdown.css';
-/**
- * The dropdown view class. It manages the dropdown button and dropdown panel.
- *
- * In most cases, the easiest way to create a dropdown is by using the {@link module:ui/dropdown/utils~createDropdown}
- * util:
- *
- * ```ts
- * const dropdown = createDropdown( locale );
- *
- * // Configure dropdown's button properties:
- * dropdown.buttonView.set( {
- * 	label: 'A dropdown',
- * 	withText: true
- * } );
- *
- * dropdown.render();
- *
- * dropdown.panelView.element.textContent = 'Content of the panel';
- *
- * // Will render a dropdown with a panel containing a "Content of the panel" text.
- * document.body.appendChild( dropdown.element );
- * ```
- *
- * If you want to add a richer content to the dropdown panel, you can use the {@link module:ui/dropdown/utils~addListToDropdown}
- * and {@link module:ui/dropdown/utils~addToolbarToDropdown} helpers. See more examples in
- * {@link module:ui/dropdown/utils~createDropdown} documentation.
- *
- * If you want to create a completely custom dropdown, then you can compose it manually:
- *
- * ```ts
- * const button = new DropdownButtonView( locale );
- * const panel = new DropdownPanelView( locale );
- * const dropdown = new DropdownView( locale, button, panel );
- *
- * button.set( {
- * 	label: 'A dropdown',
- * 	withText: true
- * } );
- *
- * dropdown.render();
- *
- * panel.element.textContent = 'Content of the panel';
- *
- * // Will render a dropdown with a panel containing a "Content of the panel" text.
- * document.body.appendChild( dropdown.element );
- * ```
- *
- * However, dropdown created this way will contain little behavior. You will need to implement handlers for actions
- * such as {@link module:ui/bindings/clickoutsidehandler~clickOutsideHandler clicking outside an open dropdown}
- * (which should close it) and support for arrow keys inside the panel. Therefore, unless you really know what
- * you do and you really need to do it, it is recommended to use the {@link module:ui/dropdown/utils~createDropdown} helper.
- */
-export class DropdownView extends View {
-    /**
-     * Button of the dropdown view. Clicking the button opens the {@link #panelView}.
-     */
-    buttonView;
-    /**
-     * Panel of the dropdown. It opens when the {@link #buttonView} is
-     * {@link module:ui/button/button~Button#event:execute executed} (i.e. clicked).
-     *
-     * Child views can be added to the panel's `children` collection:
-     *
-     * ```ts
-     * dropdown.panelView.children.add( childView );
-     * ```
-     *
-     * See {@link module:ui/dropdown/dropdownpanelview~DropdownPanelView#children} and
-     * {@link module:ui/viewcollection~ViewCollection#add}.
-     */
-    panelView;
-    /**
-     * Tracks information about the DOM focus in the dropdown.
-     */
-    focusTracker;
-    /**
-     * Instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}. It manages
-     * keystrokes of the dropdown:
-     *
-     * * <kbd>▼</kbd> opens the dropdown,
-     * * <kbd>◀</kbd> and <kbd>Esc</kbd> closes the dropdown.
-     */
-    keystrokes;
-    /**
-     * A child {@link module:ui/list/listview~ListView list view} of the dropdown located
-     * in its {@link module:ui/dropdown/dropdownview~DropdownView#panelView panel}.
-     *
-     * **Note**: Only supported when dropdown has list view added using {@link module:ui/dropdown/utils~addListToDropdown}.
-     */
-    listView;
-    /**
-     * A child toolbar of the dropdown located in the
-     * {@link module:ui/dropdown/dropdownview~DropdownView#panelView panel}.
-     *
-     * **Note**: Only supported when dropdown has a toolbar added using {@link module:ui/dropdown/utils~addToolbarToDropdown}.
-     */
-    toolbarView;
-    /**
-     * A child menu component of the dropdown located
-     * in its {@link module:ui/dropdown/dropdownview~DropdownView#panelView panel}.
-     *
-     * **Note**: Only supported when dropdown has a menu added using {@link module:ui/dropdown/utils~addMenuToDropdown}.
-     */
-    menuView;
-    /**
-     * Creates an instance of the dropdown.
-     *
-     * Also see {@link #render}.
-     *
-     * @param locale The localization services instance.
-     */
-    constructor(locale, buttonView, panelView) {
-        super(locale);
-        const bind = this.bindTemplate;
-        this.buttonView = buttonView;
-        this.panelView = panelView;
-        this.set('isOpen', false);
-        this.set('isEnabled', true);
-        this.set('class', undefined);
-        this.set('id', undefined);
-        this.set('panelPosition', 'auto');
-        // Toggle the visibility of the panel when the dropdown becomes open.
-        this.panelView.bind('isVisible').to(this, 'isOpen');
-        this.keystrokes = new KeystrokeHandler();
-        this.focusTracker = new FocusTracker();
-        this.setTemplate({
-            tag: 'div',
-            attributes: {
-                class: [
-                    'ck',
-                    'ck-dropdown',
-                    bind.to('class'),
-                    bind.if('isEnabled', 'ck-disabled', value => !value)
-                ],
-                id: bind.to('id'),
-                'aria-describedby': bind.to('ariaDescribedById')
-            },
-            children: [
-                buttonView,
-                panelView
-            ]
-        });
-        buttonView.extendTemplate({
-            attributes: {
-                class: [
-                    'ck-dropdown__button'
-                ],
-                'data-cke-tooltip-disabled': bind.to('isOpen')
-            }
-        });
-    }
-    /**
-     * @inheritDoc
-     */
-    render() {
-        super.render();
-        this.focusTracker.add(this.buttonView.element);
-        this.focusTracker.add(this.panelView.element);
-        // Toggle the dropdown when its button has been clicked.
-        this.listenTo(this.buttonView, 'open', () => {
-            this.isOpen = !this.isOpen;
-        });
-        // Let the dropdown control the position of the panel. The position must
-        // be updated every time the dropdown is open.
-        this.on('change:isOpen', (evt, name, isOpen) => {
-            if (!isOpen) {
-                return;
-            }
-            // If "auto", find the best position of the panel to fit into the viewport.
-            // Otherwise, simply assign the static position.
-            if (this.panelPosition === 'auto') {
-                const optimalPanelPosition = DropdownView._getOptimalPosition({
-                    element: this.panelView.element,
-                    target: this.buttonView.element,
-                    fitInViewport: true,
-                    positions: this._panelPositions
-                });
-                this.panelView.position = (optimalPanelPosition ? optimalPanelPosition.name : this._defaultPanelPositionName);
-            }
-            else {
-                this.panelView.position = this.panelPosition;
-            }
-        });
-        // Listen for keystrokes coming from within #element.
-        this.keystrokes.listenTo(this.element);
-        const closeDropdown = (data, cancel) => {
-            if (this.isOpen) {
-                this.isOpen = false;
-                cancel();
-            }
-        };
-        // Open the dropdown panel using the arrow down key, just like with return or space.
-        this.keystrokes.set('arrowdown', (data, cancel) => {
-            // Don't open if the dropdown is disabled or already open.
-            if (this.buttonView.isEnabled && !this.isOpen) {
-                this.isOpen = true;
-                cancel();
-            }
-        });
-        // Block the right arrow key (until nested dropdowns are implemented).
-        this.keystrokes.set('arrowright', (data, cancel) => {
-            if (this.isOpen) {
-                cancel();
-            }
-        });
-        // Close the dropdown using the arrow left/escape key.
-        this.keystrokes.set('arrowleft', closeDropdown);
-        this.keystrokes.set('esc', closeDropdown);
-    }
-    /**
-     * Focuses the {@link #buttonView}.
-     */
-    focus() {
-        this.buttonView.focus();
-    }
-    /**
-     * Returns {@link #panelView panel} positions to be used by the
-     * {@link module:utils/dom/position~getOptimalPosition `getOptimalPosition()`}
-     * utility considering the direction of the language the UI of the editor is displayed in.
-     */
-    get _panelPositions() {
-        const { south, north, southEast, southWest, northEast, northWest, southMiddleEast, southMiddleWest, northMiddleEast, northMiddleWest } = DropdownView.defaultPanelPositions;
-        if (this.locale.uiLanguageDirection !== 'rtl') {
-            return [
-                southEast, southWest, southMiddleEast, southMiddleWest, south,
-                northEast, northWest, northMiddleEast, northMiddleWest, north
-            ];
-        }
-        else {
-            return [
-                southWest, southEast, southMiddleWest, southMiddleEast, south,
-                northWest, northEast, northMiddleWest, northMiddleEast, north
-            ];
-        }
-    }
-    /**
-     * Returns the default position of the dropdown panel based on the direction of the UI language.
-     * It is used when the {@link #panelPosition} is set to `'auto'` and the panel has not found a
-     * suitable position to fit into the viewport.
-     */
-    get _defaultPanelPositionName() {
-        return this.locale.uiLanguageDirection === 'rtl' ? 'sw' : 'se';
-    }
-    /**
-     * A set of positioning functions used by the dropdown view to determine
-     * the optimal position (i.e. fitting into the browser viewport) of its
-     * {@link module:ui/dropdown/dropdownview~DropdownView#panelView panel} when
-     * {@link module:ui/dropdown/dropdownview~DropdownView#panelPosition} is set to 'auto'`.
-     *
-     * The available positioning functions are as follow:
-     *
-     * **South**
-     *
-     * * `south`
-     *
-     * ```
-     *			[ Button ]
-     *		+-----------------+
-     *		|      Panel      |
-     *		+-----------------+
-     * ```
-     *
-     * * `southEast`
-     *
-     * ```
-     *		[ Button ]
-     *		+-----------------+
-     *		|      Panel      |
-     *		+-----------------+
-     * ```
-     *
-     * * `southWest`
-     *
-     * ```
-     *		         [ Button ]
-     *		+-----------------+
-     *		|      Panel      |
-     *		+-----------------+
-     * ```
-     *
-     * * `southMiddleEast`
-     *
-     * ```
-     *		  [ Button ]
-     *		+-----------------+
-     *		|      Panel      |
-     *		+-----------------+
-     * ```
-     *
-     * * `southMiddleWest`
-     *
-     * ```
-     *		       [ Button ]
-     *		+-----------------+
-     *		|      Panel      |
-     *		+-----------------+
-     * ```
-     *
-     * **North**
-     *
-     * * `north`
-     *
-     * ```
-     *		+-----------------+
-     *		|      Panel      |
-     *		+-----------------+
-     *		    [ Button ]
-     * ```
-     *
-     * * `northEast`
-     *
-     * ```
-     *		+-----------------+
-     *		|      Panel      |
-     *		+-----------------+
-     *		[ Button ]
-     * ```
-     *
-     * * `northWest`
-     *
-     * ```
-     *		+-----------------+
-     *		|      Panel      |
-     *		+-----------------+
-     *		         [ Button ]
-     * ```
-     *
-     * * `northMiddleEast`
-     *
-     * ```
-     *		+-----------------+
-     *		|      Panel      |
-     *		+-----------------+
-     *		  [ Button ]
-     * ```
-     *
-     * * `northMiddleWest`
-     *
-     * ```
-     *		+-----------------+
-     *		|      Panel      |
-     *		+-----------------+
-     *		       [ Button ]
-     * ```
-     *
-     * Positioning functions are compatible with {@link module:utils/dom/position~DomPoint}.
-     *
-     * The name that position function returns will be reflected in dropdown panel's class that
-     * controls its placement. See {@link module:ui/dropdown/dropdownview~DropdownView#panelPosition}
-     * to learn more.
-     */
-    static defaultPanelPositions = {
-        south: (buttonRect, panelRect) => {
-            return {
-                top: buttonRect.bottom,
-                left: buttonRect.left - (panelRect.width - buttonRect.width) / 2,
-                name: 's'
-            };
-        },
-        southEast: buttonRect => {
-            return {
-                top: buttonRect.bottom,
-                left: buttonRect.left,
-                name: 'se'
-            };
-        },
-        southWest: (buttonRect, panelRect) => {
-            return {
-                top: buttonRect.bottom,
-                left: buttonRect.left - panelRect.width + buttonRect.width,
-                name: 'sw'
-            };
-        },
-        southMiddleEast: (buttonRect, panelRect) => {
-            return {
-                top: buttonRect.bottom,
-                left: buttonRect.left - (panelRect.width - buttonRect.width) / 4,
-                name: 'sme'
-            };
-        },
-        southMiddleWest: (buttonRect, panelRect) => {
-            return {
-                top: buttonRect.bottom,
-                left: buttonRect.left - (panelRect.width - buttonRect.width) * 3 / 4,
-                name: 'smw'
-            };
-        },
-        north: (buttonRect, panelRect) => {
-            return {
-                top: buttonRect.top - panelRect.height,
-                left: buttonRect.left - (panelRect.width - buttonRect.width) / 2,
-                name: 'n'
-            };
-        },
-        northEast: (buttonRect, panelRect) => {
-            return {
-                top: buttonRect.top - panelRect.height,
-                left: buttonRect.left,
-                name: 'ne'
-            };
-        },
-        northWest: (buttonRect, panelRect) => {
-            return {
-                top: buttonRect.top - panelRect.height,
-                left: buttonRect.left - panelRect.width + buttonRect.width,
-                name: 'nw'
-            };
-        },
-        northMiddleEast: (buttonRect, panelRect) => {
-            return {
-                top: buttonRect.top - panelRect.height,
-                left: buttonRect.left - (panelRect.width - buttonRect.width) / 4,
-                name: 'nme'
-            };
-        },
-        northMiddleWest: (buttonRect, panelRect) => {
-            return {
-                top: buttonRect.top - panelRect.height,
-                left: buttonRect.left - (panelRect.width - buttonRect.width) * 3 / 4,
-                name: 'nmw'
-            };
-        }
-    };
-    /**
-     * A function used to calculate the optimal position for the dropdown panel.
-     */
-    static _getOptimalPosition = getOptimalPosition;
-}

package/src/dropdown/menu/dropdownmenubehaviors.js

@@ -1,125 +0,0 @@
-/**
- * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
- */
-import { DropdownMenuListItemView } from './dropdownmenulistitemview.js';
-/**
- * @internal
- */
-export const DropdownRootMenuBehaviors = {
-    /**
-     * Move focus to a menu item on mouse hover. If it is a button to open a nested menu, open that menu.
-     */
-    toggleMenusAndFocusItemsOnHover(rootList) {
-        rootList.on('menu:mouseenter', evt => {
-            const [pathLeaf] = evt.path;
-            evt.source.focus();
-            for (const menuView of rootList.menus) {
-                const isListItemContainingMenu = pathLeaf instanceof DropdownMenuListItemView && pathLeaf.childView === menuView;
-                menuView.isOpen = (evt.path.includes(menuView) || isListItemContainingMenu) && menuView.isEnabled;
-            }
-        });
-    },
-    /**
-     * Handles the following case:
-     *
-     * 1. Hover to open a sub-menu (A). The button has focus.
-     * 2. Press arrow up/down to move focus to another sub-menu (B) button.
-     * 3. Press arrow right to open the sub-menu (B).
-     * 4. The sub-menu (A) should close (if not, there are two open menus).
-     */
-    closeMenuWhenAnotherOnTheSameLevelOpens(rootList) {
-        rootList.on('menu:change:isOpen', (evt, name, isOpen) => {
-            if (!isOpen) {
-                return;
-            }
-            const evtMenu = evt.source;
-            for (const menuView of rootList.menus) {
-                if (evtMenu.parentMenuView === menuView.parentMenuView && evtMenu !== menuView) {
-                    menuView.isOpen = false;
-                }
-            }
-        });
-    }
-};
-/**
- * @internal
- */
-export const DropdownMenuBehaviors = {
-    /**
-     * Open the menu on the right arrow key press (left, in RTL mode). This allows for navigating to sub-menus using the keyboard.
-     */
-    openOnArrowRightKey(menuView) {
-        const keystroke = menuView.locale.uiLanguageDirection === 'rtl' ? 'arrowleft' : 'arrowright';
-        menuView.keystrokes.set(keystroke, (data, cancel) => {
-            if (menuView.focusTracker.focusedElement !== menuView.buttonView.element || !menuView.isEnabled) {
-                return;
-            }
-            if (!menuView.isOpen) {
-                menuView.isOpen = true;
-            }
-            menuView.panelView.focus();
-            cancel();
-        });
-    },
-    /**
-     * Opens the menu on its button click as well as enter and space keys press (if the button is focused).
-     */
-    openOnButtonClick(menuView) {
-        menuView.buttonView.on('execute', () => {
-            if (menuView.isEnabled) {
-                menuView.isOpen = true;
-            }
-        });
-    },
-    /**
-     * Opens the menu and focuses the panel content upon pressing the Enter key.
-     */
-    openAndFocusOnEnterKeyPress(menuView) {
-        menuView.keystrokes.set('enter', (data, cancel) => {
-            // Engage only for Enter key press when the button is focused. The panel can contain
-            // other UI components and features that rely on the Enter key press.
-            if (menuView.focusTracker.focusedElement !== menuView.buttonView.element) {
-                return;
-            }
-            menuView.isOpen = true;
-            menuView.panelView.focus();
-            cancel();
-        });
-    },
-    /**
-     * Closes the menu on the left key press (right, in RTL mode). This allows for navigating to sub-menus using the keyboard.
-     */
-    closeOnArrowLeftKey(menuView) {
-        const keystroke = menuView.locale.uiLanguageDirection === 'rtl' ? 'arrowright' : 'arrowleft';
-        menuView.keystrokes.set(keystroke, (data, cancel) => {
-            if (menuView.isOpen) {
-                // Focus first, then close the panel. Otherwise, Safari won't send blur events for detached DOM elements, leading to errors.
-                menuView.focus();
-                menuView.isOpen = false;
-                cancel();
-            }
-        });
-    },
-    closeOnEscKey(menuView) {
-        menuView.keystrokes.set('esc', (data, cancel) => {
-            if (menuView.isOpen) {
-                // Focus first, then close the panel. Otherwise, Safari won't send blur events for detached DOM elements, leading to errors.
-                menuView.focus();
-                menuView.isOpen = false;
-                cancel();
-            }
-        });
-    },
-    /**
-     * Closes the menu when its parent menu closes. This prevents from leaving orphaned open menus.
-     */
-    closeOnParentClose(menuView, parentMenuView) {
-        parentMenuView.on('change:isOpen', (evt, name, isOpen) => {
-            // TODO: Remove checking `evt.source` if `change:isOpen` is no longer delegated.
-            if (!isOpen && evt.source === parentMenuView) {
-                menuView.isOpen = false;
-            }
-        });
-    }
-};

package/src/dropdown/menu/dropdownmenubuttonview.js

@@ -1,69 +0,0 @@
-/**
- * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
- */
-/**
- * @module ui/dropdown/menu/dropdownmenubuttonview
- */
-import { IconDropdownArrow } from '@ckeditor/ckeditor5-icons';
-import { IconView } from '../../icon/iconview.js';
-import { ListItemButtonView } from '../../button/listitembuttonview.js';
-import '../../../theme/components/dropdown/menu/dropdownmenubutton.css';
-/**
- * Represents a view for a dropdown menu button.
- */
-export class DropdownMenuButtonView extends ListItemButtonView {
-    /**
-     * An icon that displays an arrow to indicate a direction of the menu.
-     */
-    arrowView;
-    /**
-     * 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 = IconDropdownArrow;
-        arrowView.extendTemplate({
-            attributes: {
-                class: 'ck-dropdown-menu-list__nested-menu__button__arrow'
-            }
-        });
-        return arrowView;
-    }
-}

package/src/dropdown/menu/dropdownmenulistitembuttonview.js

@@ -1,30 +0,0 @@
-/**
- * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
- */
-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 class DropdownMenuListItemButtonView extends ButtonView {
-    id;
-    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.js

@@ -1,38 +0,0 @@
-/**
- * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
- */
-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 class DropdownMenuListItemView extends ListItemView {
-    /**
-     * The view representing either a flat item or a nested menu in a dropdown menu list item.
-     */
-    childView;
-    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);
-            }
-        }
-    }
-}