@ckeditor/ckeditor5-ui 48.2.0 → 48.3.0-alpha.1

package/dist/dropdown/dropdownview.d.ts

@@ -1,334 +1,334 @@
 /**
- * @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
- */
+* @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 type { DropdownButton } from './button/dropdownbutton.js';
-import type { DropdownPanelView, PanelPosition } from './dropdownpanelview.js';
-import type { FocusableView } from '../focuscycler.js';
-import { type ListView } from '../list/listview.js';
-import { type ToolbarView } from '../toolbar/toolbarview.js';
-import { type DropdownMenuRootListView } from './menu/dropdownmenurootlistview.js';
-import { KeystrokeHandler, FocusTracker, type Locale, type PositioningFunction } from '@ckeditor/ckeditor5-utils';
-import '../../theme/components/dropdown/dropdown.css';
+* @module ui/dropdown/dropdownview
+*/
+import { View } from "../view.js";
+import type { DropdownButton } from "./button/dropdownbutton.js";
+import type { DropdownPanelView, PanelPosition } from "./dropdownpanelview.js";
+import type { FocusableView } from "../focuscycler.js";
+import { type ListView } from "../list/listview.js";
+import { type ToolbarView } from "../toolbar/toolbarview.js";
+import { type DropdownMenuRootListView } from "./menu/dropdownmenurootlistview.js";
+import { KeystrokeHandler, FocusTracker, type Locale, type PositioningFunction } 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.
- */
+* 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 declare class DropdownView extends View<HTMLDivElement> {
-    /**
-     * Button of the dropdown view. Clicking the button opens the {@link #panelView}.
-     */
-    readonly buttonView: DropdownButton & FocusableView;
-    /**
-     * 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}.
-     */
-    readonly panelView: DropdownPanelView;
-    /**
-     * Tracks information about the DOM focus in the dropdown.
-     */
-    readonly focusTracker: 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.
-     */
-    readonly keystrokes: KeystrokeHandler;
-    /**
-     * 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?: 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?: 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?: DropdownMenuRootListView;
-    /**
-     * Controls whether the dropdown view is open, i.e. shows or hides the {@link #panelView panel}.
-     *
-     * **Note**: When the dropdown gets open, it will attempt to call `focus()` on the first child of its {@link #panelView}.
-     * See {@link module:ui/dropdown/utils~addToolbarToDropdown}, {@link module:ui/dropdown/utils~addListToDropdown}, and
-     * {@link module:ui/dropdown/utils~focusChildOnDropdownOpen} to learn more about focus management in dropdowns.
-     *
-     * @observable
-     */
-    isOpen: boolean;
-    /**
-     * Controls whether the dropdown is enabled, i.e. it can be clicked and execute an action.
-     *
-     * See {@link module:ui/button/buttonview~ButtonView#isEnabled}.
-     *
-     * @observable
-     */
-    isEnabled: boolean;
-    /**
-     * (Optional) The additional CSS class set on the dropdown {@link #element}.
-     *
-     * @observable
-     */
-    class: string | undefined;
-    /**
-     * (Optional) The `id` attribute of the dropdown (i.e. to pair with a `<label>` element).
-     *
-     * @observable
-     */
-    id: string | undefined;
-    /**
-     * The position of the panel, relative to the dropdown.
-     *
-     * **Note**: When `'auto'`, the panel will use one of the remaining positions to stay
-     * in the viewport, visible to the user. The positions correspond directly to
-     * {@link module:ui/dropdown/dropdownview~DropdownView.defaultPanelPositions default panel positions}.
-     *
-     * **Note**: This value has an impact on the
-     * {@link module:ui/dropdown/dropdownpanelview~DropdownPanelView#position} property
-     * each time the panel becomes {@link #isOpen open}.
-     *
-     * @observable
-     * @default 'auto'
-     */
-    panelPosition: PanelPosition | 'auto';
-    /**
-     * @observable
-     */
-    ariaDescribedById: string | undefined;
-    /**
-     * Creates an instance of the dropdown.
-     *
-     * Also see {@link #render}.
-     *
-     * @param locale The localization services instance.
-     */
-    constructor(locale: Locale | undefined, buttonView: DropdownButton & FocusableView, panelView: DropdownPanelView);
-    /**
-     * @inheritDoc
-     */
-    render(): void;
-    /**
-     * Focuses the {@link #buttonView}.
-     */
-    focus(): void;
-    /**
-     * 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.
-     */
-    private get _panelPositions();
-    /**
-     * 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.
-     */
-    private get _defaultPanelPositionName();
-    /**
-     * 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: Record<string, PositioningFunction>;
-    /**
-     * A function used to calculate the optimal position for the dropdown panel.
-     */
-    private static _getOptimalPosition;
+	/**
+	* Button of the dropdown view. Clicking the button opens the {@link #panelView}.
+	*/
+	readonly buttonView: DropdownButton & FocusableView;
+	/**
+	* 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}.
+	*/
+	readonly panelView: DropdownPanelView;
+	/**
+	* Tracks information about the DOM focus in the dropdown.
+	*/
+	readonly focusTracker: 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.
+	*/
+	readonly keystrokes: KeystrokeHandler;
+	/**
+	* 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?: 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?: 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?: DropdownMenuRootListView;
+	/**
+	* Controls whether the dropdown view is open, i.e. shows or hides the {@link #panelView panel}.
+	*
+	* **Note**: When the dropdown gets open, it will attempt to call `focus()` on the first child of its {@link #panelView}.
+	* See {@link module:ui/dropdown/utils~addToolbarToDropdown}, {@link module:ui/dropdown/utils~addListToDropdown}, and
+	* {@link module:ui/dropdown/utils~focusChildOnDropdownOpen} to learn more about focus management in dropdowns.
+	*
+	* @observable
+	*/
+	isOpen: boolean;
+	/**
+	* Controls whether the dropdown is enabled, i.e. it can be clicked and execute an action.
+	*
+	* See {@link module:ui/button/buttonview~ButtonView#isEnabled}.
+	*
+	* @observable
+	*/
+	isEnabled: boolean;
+	/**
+	* (Optional) The additional CSS class set on the dropdown {@link #element}.
+	*
+	* @observable
+	*/
+	class: string | undefined;
+	/**
+	* (Optional) The `id` attribute of the dropdown (i.e. to pair with a `<label>` element).
+	*
+	* @observable
+	*/
+	id: string | undefined;
+	/**
+	* The position of the panel, relative to the dropdown.
+	*
+	* **Note**: When `'auto'`, the panel will use one of the remaining positions to stay
+	* in the viewport, visible to the user. The positions correspond directly to
+	* {@link module:ui/dropdown/dropdownview~DropdownView.defaultPanelPositions default panel positions}.
+	*
+	* **Note**: This value has an impact on the
+	* {@link module:ui/dropdown/dropdownpanelview~DropdownPanelView#position} property
+	* each time the panel becomes {@link #isOpen open}.
+	*
+	* @observable
+	* @default 'auto'
+	*/
+	panelPosition: PanelPosition | "auto";
+	/**
+	* @observable
+	*/
+	ariaDescribedById: string | undefined;
+	/**
+	* Creates an instance of the dropdown.
+	*
+	* Also see {@link #render}.
+	*
+	* @param locale The localization services instance.
+	*/
+	constructor(locale: Locale | undefined, buttonView: DropdownButton & FocusableView, panelView: DropdownPanelView);
+	/**
+	* @inheritDoc
+	*/
+	override render(): void;
+	/**
+	* Focuses the {@link #buttonView}.
+	*/
+	focus(): void;
+	/**
+	* 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.
+	*/
+	private get _panelPositions();
+	/**
+	* 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.
+	*/
+	private get _defaultPanelPositionName();
+	/**
+	* 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: Record<string, PositioningFunction>;
+	/**
+	* A function used to calculate the optimal position for the dropdown panel.
+	*/
+	private static _getOptimalPosition;
 }
 /**
- * Fired when an item inside the dropdown is executed.
- *
- * **Note**: Only supported when dropdown was integrated with its child view using one of the helper functions:
- * {@link module:ui/dropdown/utils~addListToDropdown}, {@link module:ui/dropdown/utils~addToolbarToDropdown}, or
- * {@link module:ui/dropdown/utils~addMenuToDropdown}.
- *
- * When integrated with a list, it fires when a child of one of {@link module:ui/list/listitemview~ListItemView}s
- * fired `execute` event.
- *
- * When integrated with a toolbar, it fires when one of the buttons has been {@link module:ui/button/button~Button#event:execute executed}.
- *
- * When integrated with a nested menu, it fires when one of the menu buttons has been executed.
- *
- * In each case, the event is delegated from the component which fired it. It does not have additional parameters and `event.source` is the
- * original component.
- *
- * @eventName ~DropdownView#execute
- */
+* Fired when an item inside the dropdown is executed.
+*
+* **Note**: Only supported when dropdown was integrated with its child view using one of the helper functions:
+* {@link module:ui/dropdown/utils~addListToDropdown}, {@link module:ui/dropdown/utils~addToolbarToDropdown}, or
+* {@link module:ui/dropdown/utils~addMenuToDropdown}.
+*
+* When integrated with a list, it fires when a child of one of {@link module:ui/list/listitemview~ListItemView}s
+* fired `execute` event.
+*
+* When integrated with a toolbar, it fires when one of the buttons has been {@link module:ui/button/button~Button#event:execute executed}.
+*
+* When integrated with a nested menu, it fires when one of the menu buttons has been executed.
+*
+* In each case, the event is delegated from the component which fired it. It does not have additional parameters and `event.source` is the
+* original component.
+*
+* @eventName ~DropdownView#execute
+*/
 export type DropdownViewEvent = {
-    name: 'execute';
-    args: [];
+	name: "execute";
+	args: [];
 };