@ckeditor/ckeditor5-ui 42.0.2 → 43.0.0-alpha.0

package/src/menubar/menubarmenulistitemfiledialogbuttonview.d.ts

@@ -6,14 +6,14 @@
  * @module ui/menubar/menubarmenulistitemfiledialogbuttonview
  */
 import type { Locale } from '@ckeditor/ckeditor5-utils';
-import FileDialogButtonView from '../button/filedialogbuttonview.js';
+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 FileDialogButtonView {
+export default class MenuBarMenuListItemFileDialogButtonView extends FileDialogListItemButtonView {
     /**
      * Creates an instance of the menu bar list button view.
      *

package/src/menubar/menubarmenulistitemfiledialogbuttonview.js

@@ -2,14 +2,14 @@
  * @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 FileDialogButtonView from '../button/filedialogbuttonview.js';
+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 FileDialogButtonView {
+export default class MenuBarMenuListItemFileDialogButtonView extends FileDialogListItemButtonView {
     /**
      * Creates an instance of the menu bar list button view.
      *

package/src/menubar/menubarmenulistview.d.ts

@@ -21,4 +21,9 @@ export default class MenuBarMenuListView extends ListView {
      * @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

@@ -2,7 +2,10 @@
  * @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}.
  *
@@ -19,5 +22,51 @@ export default class MenuBarMenuListView extends ListView {
     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/menubarview.d.ts

@@ -28,6 +28,15 @@ export default class MenuBarView extends View implements FocusableView {
      * @observable
      */
     isOpen: boolean;
+    /**
+     * Indicates whether the menu bar has been interacted with using the keyboard.
+     *
+     * It is useful for showing focus outlines while hovering over the menu bar when
+     * interaction with the keyboard was detected.
+     *
+     * @observable
+     */
+    isFocusBorderEnabled: boolean;
     /**
      * A list of {@link module:ui/menubar/menubarmenuview~MenuBarMenuView} instances registered in the menu bar.
      *
@@ -47,7 +56,7 @@ export default class MenuBarView extends View implements FocusableView {
      * See the {@link module:core/editor/editorconfig~EditorConfig#menuBar menu bar} in the editor
      * configuration reference to learn how to configure the menu bar.
      */
-    fillFromConfig(config: NormalizedMenuBarConfigObject, componentFactory: ComponentFactory): void;
+    fillFromConfig(config: NormalizedMenuBarConfigObject, componentFactory: ComponentFactory, extraItems?: Array<MenuBarConfigAddedItem | MenuBarConfigAddedGroup | MenuBarConfigAddedMenu>): void;
     /**
      * @inheritDoc
      */

package/src/menubar/menubarview.js

@@ -37,7 +37,11 @@ export default class MenuBarView extends View {
          */
         this.menus = [];
         const t = locale.t;
-        this.set('isOpen', false);
+        const bind = this.bindTemplate;
+        this.set({
+            isOpen: false,
+            isFocusBorderEnabled: false
+        });
         this._setupIsOpenUpdater();
         this.children = this.createCollection();
         // @if CK_DEBUG_MENU_BAR // // Logs events in the main event bus of the component.
@@ -49,7 +53,8 @@ export default class MenuBarView extends View {
             attributes: {
                 class: [
                     'ck',
-                    'ck-menu-bar'
+                    'ck-menu-bar',
+                    bind.if('isFocusBorderEnabled', 'ck-menu-bar_focus-border-enabled')
                 ],
                 'aria-label': t('Editor menu bar'),
                 role: 'menubar'
@@ -64,12 +69,13 @@ export default class MenuBarView extends View {
      * See the {@link module:core/editor/editorconfig~EditorConfig#menuBar menu bar} in the editor
      * configuration reference to learn how to configure the menu bar.
      */
-    fillFromConfig(config, componentFactory) {
+    fillFromConfig(config, componentFactory, extraItems = []) {
         const locale = this.locale;
         const processedConfig = processMenuBarConfig({
             normalizedConfig: config,
             locale,
-            componentFactory
+            componentFactory,
+            extraItems
         });
         const topLevelCategoryMenuViews = processedConfig.items.map(menuDefinition => this._createMenu({
             componentFactory,
@@ -87,6 +93,7 @@ export default class MenuBarView extends View {
         MenuBarBehaviors.closeMenuWhenAnotherOnTheSameLevelOpens(this);
         MenuBarBehaviors.focusCycleMenusOnArrows(this);
         MenuBarBehaviors.closeOnClickOutside(this);
+        MenuBarBehaviors.enableFocusHighlightOnInteraction(this);
     }
     /**
      * Focuses the menu bar.

package/src/menubar/utils.d.ts

@@ -3,9 +3,8 @@
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
 import type MenuBarMenuView from './menubarmenuview.js';
-import type { default as MenuBarView, MenuBarConfig, MenuBarConfigObject, NormalizedMenuBarConfigObject } from './menubarview.js';
+import type { default as MenuBarView, MenuBarConfig, MenuBarConfigObject, MenuBarConfigAddedGroup, MenuBarConfigAddedMenu, NormalizedMenuBarConfigObject, MenuBarConfigAddedItem } from './menubarview.js';
 import type ComponentFactory from '../componentfactory.js';
-import type { Editor } from '@ckeditor/ckeditor5-core';
 import { type Locale, type PositioningFunction } from '@ckeditor/ckeditor5-utils';
 type DeepReadonly<T> = Readonly<{
     [K in keyof T]: T[K] extends string ? Readonly<T[K]> : T[K] extends Array<infer A> ? Readonly<Array<DeepReadonly<A>>> : DeepReadonly<T[K]>;
@@ -44,6 +43,11 @@ export declare const MenuBarBehaviors: {
      * Closes the bar when the user clicked outside of it (page body, editor root, etc.).
      */
     closeOnClickOutside(menuBarView: MenuBarView): void;
+    /**
+     * Tracks the keyboard focus interaction on the menu bar view. It is used to determine if the nested items
+     * of the menu bar should render focus rings after first interaction with the keyboard.
+     */
+    enableFocusHighlightOnInteraction(menuBarView: MenuBarView): void;
 };
 /**
  * Behaviors of the {@link module:ui/menubar/menubarmenuview~MenuBarMenuView} component.
@@ -233,6 +237,12 @@ export declare const MenuBarMenuViewPanelPositioningFunctions: Record<string, Po
  * 				]
  * 			},
  * 			{
+ * 				groupId: 'previewMergeFields',
+ * 				items: [
+ * 					'menuBar:previewMergeFields'
+ * 				]
+ * 			},
+ * 			{
  * 				groupId: 'restrictedEditingException',
  * 				items: [
  * 					'menuBar:restrictedEditingException'
@@ -257,7 +267,8 @@ export declare const MenuBarMenuViewPanelPositioningFunctions: Record<string, Po
  * 				groupId: 'insertInline',
  * 				items: [
  * 					'menuBar:link',
- * 					'menuBar:comment'
+ * 					'menuBar:comment',
+ * 					'menuBar:insertMergeField'
  * 				]
  * 			},
  * 			{
@@ -427,15 +438,10 @@ export declare function normalizeMenuBarConfig(config: Readonly<MenuBarConfig>):
  * * Purged empty menus,
  * * Localized top-level menu labels.
  */
-export declare function processMenuBarConfig({ normalizedConfig, locale, componentFactory }: {
+export declare function processMenuBarConfig({ normalizedConfig, locale, componentFactory, extraItems }: {
     normalizedConfig: NormalizedMenuBarConfigObject;
     locale: Locale;
     componentFactory: ComponentFactory;
+    extraItems: Array<MenuBarConfigAddedItem | MenuBarConfigAddedGroup | MenuBarConfigAddedMenu>;
 }): NormalizedMenuBarConfigObject;
-/**
- * Initializes menu bar for given editor.
- *
- * @internal
- */
-export declare function _initMenuBar(editor: Editor, menuBarView: MenuBarView): void;
 export {};

package/src/menubar/utils.js

@@ -21,20 +21,24 @@ export const MenuBarBehaviors = {
      */
     toggleMenusAndFocusItemsOnHover(menuBarView) {
         menuBarView.on('menu:mouseenter', evt => {
-            // This works only when the menu bar has already been open and the user hover over the menu bar.
-            if (!menuBarView.isOpen) {
+            // This behavior should be activated when one of condition is present:
+            // 1. The user opened any submenu of menubar and hover over items in the menu bar.
+            // 2. The user focused whole menubar using keyboard interaction and enabled focus borders and hover over items in the menu bar.
+            if (!menuBarView.isFocusBorderEnabled && !menuBarView.isOpen) {
                 return;
             }
-            for (const menuView of menuBarView.menus) {
-                // @if CK_DEBUG_MENU_BAR // const wasOpen = menuView.isOpen;
-                const pathLeaf = evt.path[0];
-                const isListItemContainingMenu = pathLeaf instanceof MenuBarMenuListItemView && pathLeaf.children.first === menuView;
-                menuView.isOpen = (evt.path.includes(menuView) || isListItemContainingMenu) && menuView.isEnabled;
-                // @if CK_DEBUG_MENU_BAR // if ( wasOpen !== menuView.isOpen ) {
-                // @if CK_DEBUG_MENU_BAR // console.log( '[BEHAVIOR] toggleMenusAndFocusItemsOnHover(): Toggle',
-                // @if CK_DEBUG_MENU_BAR // 	logMenu( menuView ), 'isOpen', menuView.isOpen
-                // @if CK_DEBUG_MENU_BAR // );
-                // @if CK_DEBUG_MENU_BAR // }
+            if (menuBarView.isOpen) {
+                for (const menuView of menuBarView.menus) {
+                    // @if CK_DEBUG_MENU_BAR // const wasOpen = menuView.isOpen;
+                    const pathLeaf = evt.path[0];
+                    const isListItemContainingMenu = pathLeaf instanceof MenuBarMenuListItemView && pathLeaf.children.first === menuView;
+                    menuView.isOpen = (evt.path.includes(menuView) || isListItemContainingMenu) && menuView.isEnabled;
+                    // @if CK_DEBUG_MENU_BAR // if ( wasOpen !== menuView.isOpen ) {
+                    // @if CK_DEBUG_MENU_BAR // console.log( '[BEHAVIOR] toggleMenusAndFocusItemsOnHover(): Toggle',
+                    // @if CK_DEBUG_MENU_BAR // 	logMenu( menuView ), 'isOpen', menuView.isOpen
+                    // @if CK_DEBUG_MENU_BAR // );
+                    // @if CK_DEBUG_MENU_BAR // }
+                }
             }
             evt.source.focus();
         });
@@ -111,6 +115,40 @@ export const MenuBarBehaviors = {
             callback: () => menuBarView.close(),
             contextElements: () => menuBarView.children.map(child => child.element)
         });
+    },
+    /**
+     * Tracks the keyboard focus interaction on the menu bar view. It is used to determine if the nested items
+     * of the menu bar should render focus rings after first interaction with the keyboard.
+     */
+    enableFocusHighlightOnInteraction(menuBarView) {
+        let isKeyPressed = false;
+        menuBarView.on('change:isOpen', (_, evt, isOpen) => {
+            if (!isOpen) {
+                menuBarView.isFocusBorderEnabled = false;
+                // Reset the flag when the menu bar is closed, menu items tend to intercept `keyup` event
+                // and sometimes, after pressing `enter` on focused item, `isKeyPressed` stuck in `true` state.
+                isKeyPressed = false;
+            }
+        });
+        // After clicking menu bar list item the focus is moved to the newly opened submenu.
+        // We need to enable focus border for the submenu items because after pressing arrow down it will
+        // focus second item instead of first which is not super intuitive.
+        menuBarView.listenTo(menuBarView.element, 'click', () => {
+            if (menuBarView.isOpen && menuBarView.element.matches(':focus-within')) {
+                menuBarView.isFocusBorderEnabled = true;
+            }
+        }, { useCapture: true });
+        menuBarView.listenTo(menuBarView.element, 'keydown', () => {
+            isKeyPressed = true;
+        }, { useCapture: true });
+        menuBarView.listenTo(menuBarView.element, 'keyup', () => {
+            isKeyPressed = false;
+        }, { useCapture: true });
+        menuBarView.listenTo(menuBarView.element, 'focus', () => {
+            if (isKeyPressed) {
+                menuBarView.isFocusBorderEnabled = true;
+            }
+        }, { useCapture: true });
     }
 };
 /**
@@ -156,7 +194,9 @@ export const MenuBarMenuBehaviors = {
     openOnButtonClick(menuView) {
         menuView.buttonView.on('execute', () => {
             menuView.isOpen = true;
-            menuView.panelView.focus();
+            if (menuView.parentMenuView) {
+                menuView.panelView.focus();
+            }
         });
     },
     /**
@@ -165,9 +205,6 @@ export const MenuBarMenuBehaviors = {
     toggleOnButtonClick(menuView) {
         menuView.buttonView.on('execute', () => {
             menuView.isOpen = !menuView.isOpen;
-            if (menuView.isOpen) {
-                menuView.panelView.focus();
-            }
         });
     },
     /**
@@ -420,6 +457,12 @@ export const MenuBarMenuViewPanelPositioningFunctions = {
  * 				]
  * 			},
  * 			{
+ * 				groupId: 'previewMergeFields',
+ * 				items: [
+ * 					'menuBar:previewMergeFields'
+ * 				]
+ * 			},
+ * 			{
  * 				groupId: 'restrictedEditingException',
  * 				items: [
  * 					'menuBar:restrictedEditingException'
@@ -444,7 +487,8 @@ export const MenuBarMenuViewPanelPositioningFunctions = {
  * 				groupId: 'insertInline',
  * 				items: [
  * 					'menuBar:link',
- * 					'menuBar:comment'
+ * 					'menuBar:comment',
+ * 					'menuBar:insertMergeField'
  * 				]
  * 			},
  * 			{
@@ -670,9 +714,15 @@ export const DefaultMenuBarItems = [
                 ]
             },
             {
-                groupId: 'restrictedEditingException',
+                groupId: 'previewMergeFields',
                 items: [
-                    'menuBar:restrictedEditingException'
+                    'menuBar:previewMergeFields'
+                ]
+            },
+            {
+                groupId: 'restrictedEditing',
+                items: [
+                    'menuBar:restrictedEditing'
                 ]
             }
         ]
@@ -694,7 +744,8 @@ export const DefaultMenuBarItems = [
                 groupId: 'insertInline',
                 items: [
                     'menuBar:link',
-                    'menuBar:comment'
+                    'menuBar:comment',
+                    'menuBar:insertMergeField'
                 ]
             },
             {
@@ -702,6 +753,7 @@ export const DefaultMenuBarItems = [
                 items: [
                     'menuBar:mediaEmbed',
                     'menuBar:insertTemplate',
+                    'menuBar:specialCharacters',
                     'menuBar:blockQuote',
                     'menuBar:codeBlock',
                     'menuBar:htmlEmbed'
@@ -716,9 +768,9 @@ export const DefaultMenuBarItems = [
                 ]
             },
             {
-                groupId: 'restrictedEditing',
+                groupId: 'restrictedEditingException',
                 items: [
-                    'menuBar:restrictedEditing'
+                    'menuBar:restrictedEditingException'
                 ]
             }
         ]
@@ -885,10 +937,11 @@ export function normalizeMenuBarConfig(config) {
  * * Purged empty menus,
  * * Localized top-level menu labels.
  */
-export function processMenuBarConfig({ normalizedConfig, locale, componentFactory }) {
+export function processMenuBarConfig({ normalizedConfig, locale, componentFactory, extraItems }) {
     const configClone = cloneDeep(normalizedConfig);
+    handleAdditions(normalizedConfig, configClone, extraItems);
     handleRemovals(normalizedConfig, configClone);
-    handleAdditions(normalizedConfig, configClone);
+    handleAdditions(normalizedConfig, configClone, configClone.addItems);
     purgeUnavailableComponents(normalizedConfig, configClone, componentFactory);
     purgeEmptyMenus(normalizedConfig, configClone);
     localizeMenuLabels(configClone, locale);
@@ -953,13 +1006,15 @@ function handleRemovals(originalConfig, config) {
     }
 }
 /**
- * Handles the `config.menuBar.addItems` configuration. It allows for adding menus, groups, and items at arbitrary
+ * Adds provided items to config. It allows for adding menus, groups, and items at arbitrary
  * positions in the menu bar. If the position does not exist, a warning is logged.
  */
-function handleAdditions(originalConfig, config) {
-    const itemsToBeAdded = config.addItems;
+function handleAdditions(originalConfig, config, items) {
     const successFullyAddedItems = [];
-    for (const itemToAdd of itemsToBeAdded) {
+    if (items.length == 0) {
+        return;
+    }
+    for (const itemToAdd of items) {
         const relation = getRelationFromPosition(itemToAdd.position);
         const relativeId = getRelativeIdFromPosition(itemToAdd.position);
         // Adding a menu.
@@ -1038,7 +1093,7 @@ function handleAdditions(originalConfig, config) {
             }
         }
     }
-    for (const addedItemConfig of itemsToBeAdded) {
+    for (const addedItemConfig of items) {
         if (!successFullyAddedItems.includes(addedItemConfig)) {
             /**
              * There was a problem processing the configuration of the menu bar. The configured item could not be added
@@ -1322,27 +1377,3 @@ function getIdFromGroupItem(item) {
 function isMenuDefinition(definition) {
     return typeof definition === 'object' && 'menuId' in definition;
 }
-/**
- * Initializes menu bar for given editor.
- *
- * @internal
- */
-export function _initMenuBar(editor, menuBarView) {
-    const menuBarViewElement = menuBarView.element;
-    editor.ui.focusTracker.add(menuBarViewElement);
-    editor.keystrokes.listenTo(menuBarViewElement);
-    const normalizedMenuBarConfig = normalizeMenuBarConfig(editor.config.get('menuBar') || {});
-    menuBarView.fillFromConfig(normalizedMenuBarConfig, editor.ui.componentFactory);
-    editor.keystrokes.set('Esc', (data, cancel) => {
-        if (menuBarViewElement.contains(editor.ui.focusTracker.focusedElement)) {
-            editor.editing.view.focus();
-            cancel();
-        }
-    });
-    editor.keystrokes.set('Alt+F9', (data, cancel) => {
-        if (!menuBarViewElement.contains(editor.ui.focusTracker.focusedElement)) {
-            menuBarView.focus();
-            cancel();
-        }
-    });
-}

package/src/panel/balloon/balloonpanelview.d.ts

@@ -110,10 +110,18 @@ export default class BalloonPanelView extends View {
      * @private
      */
     private _pinWhenIsVisibleCallback;
+    /**
+     * An instance of resize observer used to detect if target element is still visible.
+     */
+    private _resizeObserver;
     /**
      * @inheritDoc
      */
     constructor(locale?: Locale);
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
     /**
      * Shows the panel.
      *
@@ -157,8 +165,10 @@ export default class BalloonPanelView extends View {
      *
      * @param options Positioning options compatible with {@link module:utils/dom/position~getOptimalPosition}.
      * Default `positions` array is {@link module:ui/panel/balloon/balloonpanelview~BalloonPanelView.defaultPositions}.
+     * @returns Whether the balloon was shown and successfully attached or not. Attaching can fail if the target
+     * provided in the options is invisible (e.g. element detached from DOM).
      */
-    attachTo(options: Partial<PositionOptions>): void;
+    attachTo(options: Partial<PositionOptions>): boolean;
     /**
      * Works the same way as the {@link #attachTo} method except that the position of the panel is
      * continuously updated when:
@@ -202,6 +212,8 @@ export default class BalloonPanelView extends View {
      * Starts managing the pinned state of the panel. See {@link #pin}.
      *
      * @param options Positioning options compatible with {@link module:utils/dom/position~getOptimalPosition}.
+     * @returns Whether the balloon was shown and successfully attached or not. Attaching can fail if the target
+     * provided in the options is invisible (e.g. element detached from DOM).
      */
     private _startPinning;
     /**

package/src/panel/balloon/balloonpanelview.js

@@ -6,7 +6,7 @@
  * @module ui/panel/balloon/balloonpanelview
  */
 import View from '../../view.js';
-import { getOptimalPosition, global, isRange, toUnit } from '@ckeditor/ckeditor5-utils';
+import { getOptimalPosition, global, isRange, toUnit, isVisible, ResizeObserver } from '@ckeditor/ckeditor5-utils';
 import { isElement } from 'lodash-es';
 import '../../../theme/components/panel/balloonpanel.css';
 const toPx = /* #__PURE__ */ toUnit('px');
@@ -79,6 +79,7 @@ class BalloonPanelView extends View {
         this.set('withArrow', true);
         this.set('class', undefined);
         this._pinWhenIsVisibleCallback = null;
+        this._resizeObserver = null;
         this.content = this.createCollection();
         this.setTemplate({
             tag: 'div',
@@ -99,6 +100,13 @@ class BalloonPanelView extends View {
             children: this.content
         });
     }
+    /**
+     * @inheritDoc
+     */
+    destroy() {
+        this.hide();
+        super.destroy();
+    }
     /**
      * Shows the panel.
      *
@@ -146,8 +154,14 @@ class BalloonPanelView extends View {
      *
      * @param options Positioning options compatible with {@link module:utils/dom/position~getOptimalPosition}.
      * Default `positions` array is {@link module:ui/panel/balloon/balloonpanelview~BalloonPanelView.defaultPositions}.
+     * @returns Whether the balloon was shown and successfully attached or not. Attaching can fail if the target
+     * provided in the options is invisible (e.g. element detached from DOM).
      */
     attachTo(options) {
+        const target = getDomElement(options.target);
+        if (target && !isVisible(target)) {
+            return false;
+        }
         this.show();
         const defaultPositions = BalloonPanelView.defaultPositions;
         const positionOptions = Object.assign({}, {
@@ -180,6 +194,7 @@ class BalloonPanelView extends View {
         this.left = left;
         this.position = position;
         this.withArrow = withArrow;
+        return true;
     }
     /**
      * Works the same way as the {@link #attachTo} method except that the position of the panel is
@@ -217,6 +232,9 @@ class BalloonPanelView extends View {
      */
     pin(options) {
         this.unpin();
+        if (!this._startPinning(options)) {
+            return;
+        }
         this._pinWhenIsVisibleCallback = () => {
             if (this.isVisible) {
                 this._startPinning(options);
@@ -225,7 +243,6 @@ class BalloonPanelView extends View {
                 this._stopPinning();
             }
         };
-        this._startPinning(options);
         // Control the state of the listeners depending on whether the panel is visible
         // or not.
         // TODO: Use on() (https://github.com/ckeditor/ckeditor5-utils/issues/144).
@@ -249,9 +266,13 @@ class BalloonPanelView extends View {
      * Starts managing the pinned state of the panel. See {@link #pin}.
      *
      * @param options Positioning options compatible with {@link module:utils/dom/position~getOptimalPosition}.
+     * @returns Whether the balloon was shown and successfully attached or not. Attaching can fail if the target
+     * provided in the options is invisible (e.g. element detached from DOM).
      */
     _startPinning(options) {
-        this.attachTo(options);
+        if (!this.attachTo(options)) {
+            return false;
+        }
         const targetElement = getDomElement(options.target);
         const limiterElement = options.limiter ? getDomElement(options.limiter) : global.document.body;
         // Then we need to listen on scroll event of eny element in the document.
@@ -271,6 +292,19 @@ class BalloonPanelView extends View {
         this.listenTo(global.window, 'resize', () => {
             this.attachTo(options);
         });
+        // Hide the panel if the target element is no longer visible.
+        if (targetElement && !this._resizeObserver) {
+            const checkVisibility = () => {
+                // If the target element is no longer visible, hide the panel.
+                if (!isVisible(targetElement)) {
+                    this.unpin();
+                }
+            };
+            // Element is being resized to 0x0 after it's parent became hidden,
+            // so we need to check size in order to determine if it's visible or not.
+            this._resizeObserver = new ResizeObserver(targetElement, checkVisibility);
+        }
+        return true;
     }
     /**
      * Stops managing the pinned state of the panel. See {@link #pin}.
@@ -278,6 +312,10 @@ class BalloonPanelView extends View {
     _stopPinning() {
         this.stopListening(global.document, 'scroll');
         this.stopListening(global.window, 'resize');
+        if (this._resizeObserver) {
+            this._resizeObserver.destroy();
+            this._resizeObserver = null;
+        }
     }
     /**
      * Returns available {@link module:ui/panel/balloon/balloonpanelview~BalloonPanelView}

package/src/search/filtergroupanditemnames.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @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 type ViewCollection from '../viewcollection.js';
+import type ListItemGroupView from '../list/listitemgroupview.js';
+import type ListItemView from '../list/listitemview.js';
+import type ListSeparatorView from '../list/listseparatorview.js';
+/**
+ * A filter function that returns matching item and group names in the list view.
+ */
+export default function filterGroupAndItemNames(regExp: RegExp | null, items: ViewCollection<ListItemGroupView | ListItemView | ListSeparatorView>): {
+    resultsCount: number;
+    totalItemsCount: number;
+};